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Preface 


This High Performance Storage System (HPSS) Programmer's Reference Guide, Release 6.2, documents client 
function calls which are provided by HPSS. It is designed for application programmers. 

The document provides the programming reference for HPSS Release 6.2. In particular, the HPSS Client 
Application Programming Interfaces (APIs), 64-bit arithmetic library calls, Site Interfaces, ACL Interfaces, 
Configuration Parser Interfaces, and Real Time Monitoring System Interfaces are described. The 64-bit arithmetic 
library APIs are included since some Client APIs require 64-bit unsigned integer fields. 

The objective of this document is to meet the following general goals: 

• Define any known limitations of the APIs. 

• Define the application programming interfaces (APIs) provided for use by other subsystems or clients. 

• Define the data definitions referenced by the APIs. 

Starting with Release 6.2, the legacy hpss ReadList and hpss WriteList functions are being replaced with the new 
HPSS Parallel I/O (PIO) functions. Therefore the legacy information has been removed from this document to the 
HPSS Programmer’s Reference - I/O Supplement document. For sites requiring information on the legacy 
functions, please contact your Support Representative to obtain the supplemental document. 

Refer to the HPSS User’s Guide for a description of the following command line interfaces: standard FTP, parallel 
FTP, HPSS File System client and user utilities. 

Refer to the HPSS Error Messages Manual for a list of all HPSS error and advisory messages which are output by 
the HPSS software. For each message, the following information is provided: message identifier and text, source file 
name(s) which generate the message, problem description, system action, and administrator action. 

Refer to the HPSS Installation Guide and HPSS Management Guide for descriptions of the interfaces provided to 
HPSS administrators. 

The HPSS Programmer's Reference is structured as follows: 

Overview 

This chapter provides an overview of each type of programmer interface, constraints, and required libraries. 

Client API 

This chapter defines the Client API specifications and associated data definitions. 

Math Library 

This chapter defines the 64-bit arithmetic library API specifications and associated data definitions. 

Site Interfaces 

This chapter defines the Account Validation and Gatekeeper Site Interface specifications and associated data 
definitions. 

ACL API 

This chapter defines the specifications and associated data definitions for the Access Control List (ACL) API. 
Configuration Parser 
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This chapter defines the specifications and associated data definitions for the Configuration Parser Interface. 

Real Time Monitoring 

This chapter defines the specifications and associated data definitions for the Real Time Monitoring Service. 
Glossary of Terms and Acronyms 

This appendix provides a list of HPSS related terms and acronyms used in this document. 

References 

This appendix lists documents cited in the text as well as other reference materials. 

Acknowlegments 

This appendix acknowledges contributions to the HPSS development. 

Typographic and Keying Conventions 

This document uses the following typographic conventions: 

Bold Bold words or characters represent system elements to be used literally, such as functions, commands or 
keywords. 

Italic Italic words or characters represent variable values to be supplied. 

[ ] Brackets enclose optional items in syntax and format descriptions. 

{} Braces enclose a list of items to select in syntax and format descriptions. 
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Chapter 1. Overview 

The High Performance Storage System (HPSS) provides scalable parallel storage systems for highly parallel 
computers as well as traditional supercomputers and workstation clusters. Concentrating on meeting the high end of 
storage system and data management requirements, HPSS is scalable and designed for large storage capacities, and 
to use network-connected storage devices to transfer data at rates up to multiple gigabytes per second. Listed below 
are the programming interfaces for accessing data from HPSS. 

1.1. Client API 

1.1.1. Purpose 

The purpose of the Client API is to provide an interface which mirrors the POSIX. 1 specification where possible to 
provide ease of use to the POSIX application programmer. In addition, extensions to allow the programmer to take 
advantage of the specific features provided by HPSS are provided (e.g., storage/access hints passed on file creation, 
parallel data transfers, migration, and purge). 

1.1.2. Components 

The Client API consists of these major parts: 

• File Open/Creation and Close Operations 

• File Data Access Operations 

• Fileset/Junction Creation and Deletion Operations 

• File Attribute Operations 

• File Name Operations 

• Directory Creation and Deletion Operations 

• Directory Access Operations 

• Working Directory Operations 

• Client API Control Operations 

• Security Context Routines 

• Core Server Statistic Operations 

• HPSS Object Manipulation Routines 

• Streams File Operations 

File Open/Creation and Close Operations provide functions to create a file, open existing files and close previously 
opened files. The functions within this section are hpss_Open, hpss_OpenHandle, hpss_Close, 
hpss_Creat,hpss_Create, hpssCreateHandle, hpssCreateDMHandle, hpssOpenBitfile, 
hpss OpenBitfileVAttrs, hpssSetCOSByHints, and hpss ReopenBitfile. 

File Data Access Operations provide functions to read from and write data to HPSS files. The functions within this 
section include hpssLseek, hpssRead, hpss ReadList, hpss SetFileOffset, hpssGetDistFile, 
hpss InsertDistFile, hpssCopyFile, hpssFpreallocate, hpssWrite, hpssWriteList, hpssBeginExTrans, 
hpssEndExTrans, and hpssGetAsynchStatus. 
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Fileset/Junction Creation and Deletion Operation provide functions to create and delete filesets and junctions. Func¬ 
tions within this section include hpss_FilesetCreate, hpss FilesetDelete, hpss_FilesetGetAttributes, 
hpssFilesetSetAttributes, hpssFilesetListAll, hpssGetJunctions, hpssJunctionCreate, 
hpssJunctionCreateHandle, hpssJunctionDelete, and hpssJunctionDeleteHandle. 

File Attribute Operations include functions to query and alter a file’s attribute values (both via POSIX consistent 
interfaces and extended HPSS interfaces), and determine a client’s accessibility to a file or directory. Functions 
within this section are hpssAccess, hpss AccessHandle, hpssAcctCodeToName, hpssAcctNameToCode, 
hpssChacct, hpss ChacctByName, hpssChmod, hpssChown, hpssConvertldsToNames, 
hpssConvertNamesToIds, hpssDeleteACL, hpssDeleteACLHandle, hpssFclear, hpssFclearOffset, 
hpssFileGetAttributes, hpssFileGetAttributesHandle, hpss GetAttrHandle, hpssFileGetAttributesSOID, 
hpssFileGetXAttributes, hpss GetRawAttrHandle, hpssFileSetAttributes, hpssFileSetAttributesHandle, 
hpssFileSetAttributesSOID, hpssFstat, hpssFtruncate, hpssGetAcct, hpssGetAcctName, hpssGetACL, 
hpssGetACLHandle, hpssGetListAttrs, hpssGetJunctionAttrs, hpssLstat, hpssMigrate, hpssPurge, 
hpssSetACL, hpss SetACLHandle, hpssSetAcct, hpssSetAcctByName, hpss SiteldToName, 
hpss SiteNameToId, hpssStage, hpss StageCallBack, hpss Stat, hpss Statfs, hpss Statvfs, hpss Truncate, 
hpss TruncateHandle, hpss Umask, hpss UpdateACL, hpss UpdateACLHandle, hpss Utime, and 
hpssPurgeLock. 

File Name Operations are used to rename files and directories and remove a name associated with a file. Functions 
within this section include hpss Link, hpss LinkHandle, hpss Readlink, hpss ReadlinkHandle, 
hpss Rename, hpss RenameHandle, hpss Symlink, hpss SymlinkHandle, hpss Unlink, hpss UnlinkHandle, 
and hpssUnlinkNoLookup. 

Directory Creation and Deletion Operations provide functions to make and remove directories. Functions within this 
section include hpss Mkdir, hpss MkdirHandle, hpss Rmdir, hpss SetAttrHandle, hpss RmdirFIandle, and 
hpssRmdirNoLookup. 

Directory Access Operations provide functions to read the directory entries from a directory. Functions within this 
section include hpss Closedir, hpss Opendir, hpss ReadAttrs, hpss ReadAttrsHandle, 
hpss ReadRawAttrsHandle, hpss Readdir, hpss ReaddirHandle, and hpss Rewinddir. 

Working Directory Operations provide functions to query and alter a thread’s current working directory. Functions 
within this section include hpss_Chdir, hpss_Chroot, and hpss_Getcwd. 

The Client API Control Operations, to update and clean up a thread's Client API state information, within this 
section include hpss GetConfiguration, hpss LoadThreadState, hpss LoadDefaultThreadState, 
hpss_ThreadCleanUp, and hpss_SetConfiguration. Also included are two important internal routines: 
hpss_ClientAPIInit, and hpss_ClientAPIReset. These APIs will not be used by most applications. 

Security Context Operations provide convenience functions to establish an application program's login context, and 
subsequently purge the login context. An application program which is calling the Client API library must run on 
behalf of either a Unix or Kerberos principal. Either the user can acquire security credentials prior to submitting the 
application program, or the hpss_SetLoginCred function may be called from the application. The name of the 
principal and associated keytab file name are supplied to the function. Prior to exiting the application, the user must 
call hpss_PurgeLoginCred to delete the security context and terminate the thread which maintains the context. The 
user credentials, that the currently running thread has, can be obtained using the routine hpss GetThreadUcred. 
Security audit information can be obtained on a per thread basis using the routine hpss_SetAuditInfo. 

Core Server statistics operations provide the ability to get and reset the stage, migration, purge, and delete counts for 
the subsystem. The functions that provide these capabilities are hpss_GetSubSysStats and 
hpssResetSubSysStats. 

HPSS Object manipulation routines are hpss GetObjld, hpss GetObjType, hpss GetPathHandle, and 
hpssHandleCompare. 
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Buffered File Operations provide a "stream-like" interface for buffered I/O operations between the client and HPSS. 
These functions are: hpssFclose, hpss Fcntl, hpssFflush, hpssFopen, hpssFread, hpss Fseek, hpssFstat, 
hpssFsync, hpssFtell, and hpssFwrite. 

Additional functions are provided to allow COS hints: hpss_CreateWithHints and hpss_OpenWithHints. 

1.1.3. Constraints 

The following constraints are being imposed by the Client API: 

• The validity of open files and directories at the time of fork is undefined in the child process. 

• The validity of open files and directories is lost across calls to any of the family of exec calls. 

• The designed client API works only with applications that make use of the Core Server. In particular, this API is 
not designed to meet the needs of clients that will perform the Name Service functionality internally and/or will 
bypass the Core Server when performing storage operations. 

1.1.4. Libraries 

Applications issuing HPSS Client API calls must link with the following library: 

• libhpss.a HPSS client library 

Applications using the Posix compliant functions must link with the following library: 

• libhpssposix.a HPSS Posix library 

1.1.5. Environment Variables 

A description of environment variables used by the Client API is provided in this section. In most cases, explicit 
setting of these environment variables is only required if HPSS was installed with non-default values. Contact your 
administrator to determine the values being used or refer to the /var/hpss/etc/env.conf file for the environment 
variable settings. The following environment variables can be used to control the Client API’s working 
environment: 

The HPSS_KRB5_KEYTAB_FILE environment variable defines the name of the file containing the KRB5 
security keys necessary for successfully initializing the Client API for servers using Kerberos authentication. The 
default is /var/hpss/etc/hpss.keytab. 

The HPSS_UNIX_KEYTAB_FILE environment variable defines the name of the file containing the Unix security 
keys necessary for successfully initializing the Client API for servers using Unix authentication. The default is /var/ 
hpss/etc/hpss.unix.keytab. 

The HPSS_SEC_REALM_NAME environment variable is used to specify the security realm to use when 
initializing the HPSS security services. 

The HPSS_API_DESC_NAME environment variable is used to place a descriptive name in any HPSS message 
logged by the Client API Library. The default value is “Client Application “. This variable is only used when logging 
is enabled in the library. 

The HPSS_API_HOSTNAME environment variable is used to specify the host name to be used for TCP/IP ports 
created by the Client API. The default value is the default host name of the machine on which the Client API is 
running. This value can have a significant impact on data transfer performance for data transfers that are handled by 
the Client API (i.e., those that use the hpss Read and hpss Write interfaces). 
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The Client API, if compiled with debugging enabled, uses two environment variables to control printing debug 
information. HPSS_API_DEBUG, if set to a non-zero value, will enable debug messages. By default, these 
messages will go to the standard output stream. If HPSS_API_DEBUG_PATH is set, however, these messages will 
be directed to the file indicated by this environment variable. Two special cases for the debug path exist: "stdout" 
and "stderr'', which will use the standard output or standard error I/O streams, respectively. 

The HPSS_API_MAX_CONN identifies the integer value that will be used for the maximum number of 
connections allowed. The default is zero, which is equal to the default supported by the HPSS connection 
management software - currently 150. 

The HPSS_API_RETRIES environment variable is used to control the number of retries to attempt when an 
operation fails. Currently this class of operation includes library initialization and communications failures. A value 
of zero indicates that no retries are to be performed, and value of negative one indicates that the operation will be 
retried until successful. The default value is 4. 

The HPSS_API_BUSY_DELAY environment variable is used to control the number of seconds to delay between 
retry attempts. The default value is 15. 

The HPSS_API_BUSY_RETRIES environment variable is used to control the number of retries to be performed 
when a request fails because the Core Server does not currently have an available thread to handle that request. A 
value of zero indicates that no retries are to be performed. A value of negative one indicates that retries should be 
attempted until either the request succeeds or fails for another reason. The default value is 3. 

The HPSS_API_TOTAL_DELAY environment variable is used to control the number of total seconds to continue 
retrying requests. A value of zero indicates that no there is no time limit. The default value is 0. 

The HPSSAPILIMITEDRETRIES environment variable is used to control the number of retry attempts before 
a limited retry error operation fails. The default value is 1. 

The HPSS_API_RETRY_STAGE_INP environment variable is used to control whether retries are attempted on 
opens of files in a Class of Service that is configured for background staging on open. A non-zero value indicates 
that opens which would return -EINPROGRESS to indicate that the file is being staged will be retried (using the 
same control mechanisms described in the previous paragraph). A value of zero indicates that the -EINPROGRESS 
return code will be returned to the client. The default value is one (1). 

The HPSS_API_REUSE_CONNECTIONS environment variable is used to control whether TCP/IP connections 
are to be left open as long as a file is opened or are to be closed after each read or write request. A non-zero value 
will cause connections to remain open, while a value of zero will cause connections to be closed. The default value 
is zero. 

The HPSS_API_USE_PORT_RANGE environment variable is used to control whether the HPSS Mover(s) should 
use the configured port range when making TCP/IP connections for read and write requests. A non-zero value will 
cause the Mover(s) to use the port range. A value of zero will cause the Mover(s) to allow the operating system to 
select the port number. The default value is 0. 

The HPSS_API_DMAP_WRITE_UPDATES environment variable is used to control the frequency of cache 
invalidations that are issued to the DMAPI file system while writing to a file that is mirrored in HPSS. The default 
value is 20. 

The HPSS_API_DISABLE_CROSS_REALM is used to control cross-realm traversal. When cross -realm 
traversal is disabled, a client will not be allowed to access directories which are located in another security realm. 

The default value is 0. 

The HPSS_API_DISABLE_JUNCTIONS is used to control junction traversal. When junction traversal is 
disabled, a client will not be allowed to access directories which require traversal to the directory via an HPSS 
junction. The default value is 0. 
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The HPSS_API_TRANSFER_TYPE environment variable is used to specify the data transport mechanism to be 
used for data transfers handled by the Client API. The value should be set to "TCP" (for TCP/IP transfers) or 
"MVRSELECT". The default is MVRSELECT"TCP" (for TCP/IP transfers). 

The HPSS_API_SITE_NAME environment variable is used to control which HPSS site the client is connected to. 

The HPSS_API_AUTHN_MECH environment variable is used to control the select of an authentication 
mechanism. 

The HPSS_API_RPC_PROT_LEVEL environment variable is used to control the select of an RPC protection 
level. 

The HPSS_API_SAN3P environment variable is used to specify whether the SAN3P protocol is being supported. 

The F_HPSS_BUFSIZE_MB environment variable is used to specify a different buffer size in megabytes for the 
HPSS buffered I/O functions. The default buffer size is 256MB. 

1.2. Network Options 

The purpose of the Network Options library is to provide an interface to query the information contained in 
the HPSS network options configuration file for the local machine. This file contains information about 
network options that may be configured differently for specific network and/or nodes with which the local 
machine is communicating. 

1.3. 64-bit Arithmetic Library 

1.3.1. Purpose 

Some HPSS Client APIs require 64-bit fields. The operating system and C compiler on many workstation platforms 
may not support 64-bit integer operations. As a result, in order to support large integer fields, a set of math libraries 
have been supplied until 64-bit support is available on all pertinent vendor platforms. 

1.3.2. Components 

The Math Libraries consist of the following macros: 

• add64m Add two 64-bit unsigned integers 

• add64_3m Add two 64-bit unsigned integers and store the result in a separate parameter 

• and64m Perform a bitwise AND of two 64-bit unsigned integers 

• andbit64m AND bit position in 64-bit unsigned integer defined by 32-bit unsigned integer 

• bld64m Build a 64-bit unsigned integer from two 32-bit unsigned integers 

• cast64m Cast a 32-bit unsigned integer into a 64-bit unsigned integer 

• div64m Divide a 64-bit unsigned integer by a 32-bit unsigned integer 

• div2x64m Divide a 64-bit unsigned integer by a 64-bit unsigned integer 

• div_cl64m Divide a 64-bit unsigned integer by a 32-bit unsigned integer and return the ceiling 

• div_2xcl64m Divide a 64-bit unsigned integer by a 64-bit unsigned integer and return the ceiling 

• eqz64m Determine if a 64-bit unsigned integer is zero 
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• eq64m 

• ge64m 

• gt64m 

• high32m 

• le64m 

• low32m 

• lt64m 

• mod 64 m 

• mod2x64m 

• mul64m 

• neqz64m 

• neq64m 

• not64m 

• or64m 

• shl64m 

• shl64_-3m 

• shr64m 

• shr64_3m 

• sub64m 

• sub64_3m 


Compare two 64-bit unsigned integers for equality 

Perform greater than or equal to check between two 64-bit unsigned integers 

Perform greater than check between two unsigned 64-bit integers 

Extract the high order 32-bits of a 64-bit unsigned integer 

Perform less than or equal to check between two 64-bit unsigned integers 

Extract the low order 32-bits of a 64-bit unsigned integer 

Perform less than check between two 64-bit unsigned integers 

Modulus a 64-bit unsigned integer by a 32-bit unsigned integer 

Modulus a 64-bit unsigned integer by a 64-bit unsigned integer 

Multiply a 64-bit unsigned integer by a 32-bit unsigned integer 

Determine if a 64-bit unsigned integer is nonzero 

Determine if two 64-bit unsigned integers are not equal 

Perform a bitwise NOT of a 64-bit unsigned integer 

Perform bitwise OR of two 64-bit unsigned integers 

Shift a 64-bit unsigned integer left by an unsigned 32-bit integer count 

Shift a 64-bit unsigned integer left by an unsigned 32-bit integer count and store in a separate 64- 
bit unsigned integer 

Shift a 64-bit unsigned integer right by an unsigned 32-bit integer count 

Shift a 64-bit unsigned integer right by an unsigned 32-bit integer count and store in a separate 64- 
bit unsigned integer 

Subtract a 64-bit unsigned integer from another 64-bit unsigned integer 
Subtract two 64-bit unsigned integers and store the result in a separate parameter. 


1.3.3. Constraints 

The following constraints are being imposed by the 64-bit arithmetic functions: 

• 64-bit unsigned integer operations are sufficient, i.e. 64-bit signed arithmetic operations are not supported. 

• Multiply functions are limited to 64-bit by 32-bit unsigned operations. For example, a 64-bit unsigned integer 
may be multiplied by a 32-bit unsigned integer. No 64-bit by 64-bit operations are supported for this category of 
functions. 


1.3.4. Libraries 

The 64-bit arithmetic functions are included in the libhpss.a library. 

1.4. Storage Concepts 

This section defines key HPSS storage concepts which have a significant impact on the usability of HPSS. 
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Configuration of the HPSS storage objects and policies is the responsibility of your HPSS system administrator. 

1.4.1. Class of Service 

Class of Service (COS) is an abstraction of storage system characteristics that allows HPSS users to select a 
particular type of service based on performance, space, and functionality requirements. Each COS describes a 
desired service in terms of characteristics such as minimum and maximum file size, transfer rate, access frequency, 
latency, and valid read or write operations. A file resides in a particular COS and the class is selected when the file 
is created. Underlying a COS is a storage hierarchy that describes how data for files in that class are to be stored in 
HPSS. 

COS is specified at file create time. COS hints and priority structures are passed to HPSS in the hpss_Open 
function. Contact your HPSS system administrator to determine the Classes of Service which have been defined. 

The following command may also be used to list the defined Classes of Service: 

lshpss -cos 

Refer to Chapter 4 of the HPSS User's Guide for information on the lshpss command. A class of service is 
implemented by a Storage Hierarchy of one to many Storage Classes. Storage Hierarchies and Storage Classes are 
not directly visible to the user, but are described below since they map to a Class of Service. The relationship 
between storage class, storage hierarchy, and COS is shown in Figure 2: Class of Service / Hierarchy /Storage 
Class of the HPSS Installation Guide. 

1.4.2. Storage Class 

An HPSS Storage Class is used to group storage media together to provide storage with specific characteristics for 
HPSS data. The attributes associated with a Storage Class are both physical and logical. Physical media in HPSS 
are called physical volumes. Physical characteristics associated with physical volumes are the media type, block 
size, the estimated amount of space on volumes in this class, and how often to write tape marks on the volume (for 
tape only). Physical media are organized into logical virtual volumes. This allows striping of physical volumes. 
Some of the logical attributes associated with the Storage Class are virtual volume block size, stripe width, data 
transfer rate, latency associated with devices supporting the physical media in this class, and storage segment size 
(disk only). In addition, the Storage Class has attributes that associate it with a particular migration policy and purge 
policy to help in managing the total space in the Storage Class. 

1.4.3. Storage Hierarchy 

An HPSS Storage Hierarchy consists of multiple levels of storage with each level representing a different storage 
media (i.e., a storage class). Files are moved up and down the Storage Hierarchy via stage and migrate operations, 
respectively, based upon storage policy, usage patterns, storage availability, and user request. For example, a 
Storage Hierarchy might consist of a fast disk, followed by a fast data transfer and medium storage capacity robot 
tape system, which in turn is followed by a large data storage capacity, but relatively slow data transfer tape robot 
system. Files are placed on a particular level in the hierarchy depending on the migration policy and staging 
operations. Multiple copies of a file may also be specified in the migration policy. If data is duplicated for a file at 
multiple levels in the hierarchy, the more recent data is at the higher level (lowest level number) in the hierarchy. 
Each hierarchy level is associated with a single storage class. 

1.4.4. File Family 

A file family is an attribute of an HPSS file that is used to group a set of files on a common set of tape virtual 
volumes. Grouping of files only on tape volumes is supported. Families can only be specified by associating a 
family with a fileset, and creating the file in the fileset. When a file is migrated from disk to tape, it is migrated to a 
tape virtual volume assigned to the family associated with the file. If no family is associated with the file, the file is 
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migrated to the next available tape not associated with a family (actually to a tape associated with family zero). If no 
tape virtual volume is associated with the family, a blank tape is reassigned from family zero to the file’s family. The 
family affiliation is preserved when tapes are repacked. Configuring file families is an HPSS System Administrator's 
function. 

1.5. User Ids 

After the HPSS system is configured, the necessary accounts must be created for HPSS users. Contact your HPSS 
system administrator to add an account. For the Client API, either a Unix or Kerberos account must be created. 
The HPSS system administrator can use the following commands to add a new account. 

hpssuser -add user -krb 
hpssuser -add user -unix 

1.6. Access Control List API 

1.6.1. Purpose 

The access control list API is a set of routines for managing access control lists (ACLs). The routines provide a way 
to convert ACLs from string format into a form suitable for use by the client API routines. They also provide a way 
to call the client API routines using ACLs and string format, and a way to convert ACLs back from client API format 
to string format. In particular, the string conversion routines take care of translating user, group and realm names 
into UIDs, GIDs and Realm IDs respectively. 

1.6.2. Components 

The access control list library (libhacl) contains the following routines: 

• hacl_ConvertACLToHACL Convert ACL to string format 

• hacl_ConvertHACLToACL Convert ACL to HPSS format 

• hacl_ConvertHACLToString Convert ACL to a form suitable for printing 

• hacl_ConvertHACLPermsToPerms Convert permission string to HPSS format 

• hacl_ConvertHACLTypeToType Convert ACL entry type to HPSS format 

• hacl_ConvertPermsToHACLPerms Convert HPSS permission mask to string 

• hacl_ConvertStringsToHACL Convert ACL strings to HACL format 

• hacl_ConvertTypeToHACLType Convert ACL entry type to string 

• hacl_DeleteHACL Delete selected entries from an object’s ACL 

• hacl GetHACL Get an object’s ACL 

• hacl_SetHACL Replace an object’s ACL with a new one 

• hacl_SortHACL Sort ACL into canonical order 

• hacl_UpdateHACL Change selected entries in an object’s ACL 
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1.6.3. Constraints 

None. 

1.6.4. Libraries 

The access control list APIs are available in the HPSS Client Library, libhpss.a. 

1.6.5. Purpose 

The Real Time Monitoring API, library routines and utility routines are intended to give system administrators a tool 
to view the internal activity of the running HPSS system. The RTM library routines enable selected HPSS servers to 
store information about in-progress requests, while the RTM API in these HPSS servers allows the RTM Utility to 
collect this information and present it in a readable form. 

1.6.6. Components 

RTM consists of these major parts: 

• RTM Library 

• RTM API 

• RTM Utility 

The RTM Library 

In order to understand how requests are progressing in an HPSS system, a set of library routines I(librtm.a) are 
provided for selected HPSS servers to call to store information about each request that the server is handling. The 
current list of participating servers is the Core Server, Mover, and Gatekeeper. These library routines initialize an 
in-memory request list fskip or each HPSS server, and allow the server to insert, update and delete entries in this list. 
Associated with each request list entry that the server makes will be a wait list. This wait list will have entries that 
describe the current wait states of this request. For example, in the Core Server a tape-to-tape copy operation begins 
as a single request, so a single request entry will be entered into the request list. But ultimately there will be two 
Core Server threads working on this request. One thread might be waiting on a tape read and the other thread 
waiting on a tape write. In this case, there would be one request entry for this request id, and two waitlist entries 
associated with this request entry. On the other hand, within one server there may be more than one request entry for 
a given request id. This might happen if a tape-to- tape copy enters the Core Server with a read request and a write 
request. Both requests originate from the Core Server copy request, so both have the same request id. But these 
requests come to the Core Server separately, so the Core Server would enter a separate request entry onto its request 
list for each of these requests, and would keep the associated waitlists separate. The librtm.a routines are: 

• rtmPrelnit 

• rtmlnit 

• rtmShutdown 

• rtmReqListlnit 

• rtmReqListlnsertEntry 

• rtmReqListDeleteEntry 

• rtmReqListUpdateEntry 
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• rtmWaitListlnsertEntry 

• rtmWaitListDeleteEntry 

• rtmWaitListUpdateEntry 


The RTM API 

To retrieve the request list information from the selected HPSS servers, each server has an API that can be called by 
a client external to HPSS. This API interface, rtm_GetRequestEntries, will be exported by each of the selected 
HPSS servers. Depending upon the parameters to this call, the interface will return varying amounts of information 
about the requests in a given HPSS server's request list. This interface will be registered using a separate .idl file and 
assigned its own thread pool so that even if all threads in the server are in use, this request information can be 
retrieved. 

The RTM Utility 

The RTM Utility, rtmu, gathers and presents the request information from one or more HPSS servers. Depending 
upon the nature of the request, the utility calls the rtm_GetRequestEntries API in the appropriate HPSS server(s) 
and presents the returned request data in a short, long or script-ready output format. For example, if all requests 
active in the Core Server are requested, this utility binds to the Core Server and calls rtm_GetRequestEntries to 
retrieve the desired information. Or if the utility is told to retrieve all information in the HPSS system about a given 
request, the utility starts by binding to the Core Server and calling rtm_GetRequestEntries; and depending upon 
the results of this request, the utility may contact any associated movers. There is a variety of request options. 

1.6.7. Constraints 

The following constraints are being imposed upon HPSS as a result of this subsystem design: 

• The HPSS MVR will not be able to use all of this design approach because of using separate processes instead of 
threads, and because of the requirement for a non-DCE interface for the mover. 

1.6.8. Libraries 

Applications calling the RTM library routines must link with the following library: 

• librtm.a 

Applications calling the RTM API rtm_GetRequestEntries must link with the following libraries: 

• libgss.a 

• libhandles.a 

• libhpssapi.a 

• libhpssxdr.a 

• libhpsscomm.a 

• libhpsscs.a 

• libhpsslog.a 

• libhpssls.a 
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• libhpssavlib.a 

• libhsec.a 

• libinterop.a 

• libmetadata.a 

• libpdata.a 

• librtm.a 

• libtraniod.a 
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Chapter 2. Client API Functions 

This chapter specifies the HPSS client programming interface. Specifically, the following information is provided: 

• Standard Application Programming Interfaces (APIs) - API Interfaces 

• Structure definitions - Data Definitions 


2.1. API Interfaces 

This section describes all API interfaces which are provided for use by another HPSS subsystem or by a client 
external to HPSS. The API interface specification includes the following information: 

• Name 

• Synopsis 

• Description 

• Parameters 

• Return Values 

• Error Conditions 

• See Also 

• Notes 

Note that for each thread that issues an HPSS Client API call, a call must be made to hpss_ThreadCleanUp with the 
thread id for that thread. This is necessary so that the client API can free state and memory allocated to that thread. 

Note that there are a number of errors that may be returned from a Client API call which are not actually errors 
generated by performing the call, but are caused by a failure of the client API to successfully initialize. These values 
may be returned from any routine and include: 


EAGAIN 

ENOCONNECT 

ENOMEM 

EPERM 

EIO 

ESTALE 

ETIMEDOUT 


An HPSS server is not ready or received a communication error, and the request could 
be retried. 

The Client API could not connect to either the Location Server or the Core Server. 
Memory could not be allocated for internal Client API State. 

The user's client credentials could not be established. 

An internal HPSS error occurred. 

The open file or directory is no longer valid - close and reopen the file or directory to 
reestablish a valid open descriptor. This error is likely due to the connections to the 
HPSS servers being reset. 

An HPSS server request timed out or received a communication error, and the request 
could not be successfully retried. 


2.1.1. hpss_Access 

Purpose 
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Check file accessibility. 


Synopsis 

#include <unistd.h> 

#include "hpss_api.h" 

int 

hpss_Access( 

char *Path, /* IN */ 

int Amode ); /* IN */ 


Description 

The hpss_Access function checks the accessibility of the file named by Path for the file access indicated by 
Amode. Refer to POSIX.l for more detailed information. 

Parameters 

Path Points to the path name of the file for which client accessibility is being 

checked. 

Amode Indicates the type of file access being checked. Refer to POSIX.l for possible 

values. 

Return Values 

If the requested access is permitted, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX. 1 access. 

Error Conditions 

EACCES The permissions specified by Amode are denied, or search permission is denied 

on a component of the path prefix. 

EFAULT The Path parameter is a NULL pointer. 

EINVAL An invalid value was specified for Amode. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 

component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 

See Also 

hpss AccessHandle, hpss Chmod, hpss FileSetAttributes. 

Notes 

None. 

2.1.2. hpss_AccessHandle 

Purpose 

Check file accessibility. 
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Synopsis 

#include <unistd.h> 

#include "hpss_api.h" 
int 

hpss AccessHandle( 

IN */ 
IN */ 
IN */ 
IN */ 
OUT */ 


ns_Obj Handle_t 

char 

int 

sec_cred_t 

hps s_au thz_token_t 


*ObjHandle, /* 
*Path, /* 
Amode, /* 
*Ucred, /* 
*AuthzTicket) ; /* 


Description 

The hpss_AccessHandle function checks the accessibility of the file named by Path for the file access 
indicated by Amode. Refer to POSIX. 1 for more detailed information. 

Parameters 


ns ObjHandleJ 
Path 

Amode 

Ucred 

AuthzTicket 

Return Values 


Pointer to handle of the parent object 

Points to the path name of the file for which client accessibility is being 
checked. 

Indicates the type of file access being checked. Refer to POSIX. 1 for possible 
values. 

Pointer to User Credentials. 

Returned pointer to authorization ticket. 


If the requested access is permitted, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX. 1 access. 


The permissions specified by Amode are denied, or search permission is denied 
on a component of the path prefix. 

An invalid value was specified for Amode or the Path parameter is a NULL 
pointer. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 

component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 


Error Conditions 

EACCES 


See Also 


hpss Access, hpss Chmod, hpssFileSetAttributes. 

Notes 


None. 
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2.1.3. hpss_AcctCodeToName 

Purpose 


Finds the Account Name associated with the given Account Code 


Synopsis 


#include "hpssapi.h" 
int 

hpssAcctCodeT oN ame( 

acctrect AcctCode, /* IN */ 
hpss uuid t *Site, /* IN/OUT */ 

char *AcctName); /* OUT */ 


Description 

Finds and returns the Account Name associated with a given Account Code. 

Parameters 

AcctCode The Account Code to look up. 

Site Pointer to an area that contains the UUID of the site you are interested in. If 

this UUID is zeroed out or null, the index for the site managing the current 
working directory is used. 

AcctName The Account Name associated with the given Account Code. Account Name 

should be a string of at least HPSS_MAX_ACCOUNT_NAME (128) 
characters. 

Return Values 

Upon successful completion, hpssAcctCodeToName returns zero. Otherwise, hpssAcctCodeToName 
returns a negative value, the absolute value of which indicates the specific error. 

Error Conditions 

EFAULT The AcctName is a NULL pointer or UUID compare for site failed. 

EINVAL The given AccountCode is not valid. 

See Also 

hpssAcctN ameToCode 

Notes 

None. 

2.1.4. hpss_AcctNameToCode 

Purpose 

Finds the Account Code associated with the given Account Name 

Synopsis 

#include "hpss api.h" 
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int 

hpssAcctN ameToCode( 

char *AcctName, 

hpssuuidt *Site, 

acct rec t *AcctCode ); 


/* IN/OUT */ 
/* IN/OUT */ 
/* OUT */ 


Description 

Finds and returns the Account Code associated with a give Account Name. 

Parameters 

AcctName 
Site 

AcctCode 

Return Values 

Upon successful completion, hpssAcctNameToCode returns zero. Otherwise, hpssAcctNameToCode 
returns a negative value, the absolute value of which indicates the specific error. 

Error Conditions 

E1NVAL The given Account Name is not valid. 

EFAULT The account name or account code is a NULL pointer. 

ENAMETOOLONG The account name is too long. 

See Also 

hpssAcctCodeT oN ame 

Notes 

None. 


Pointer to the Account Name to look up. 

Pointer to an area that contains the UUID of the site. If this UUID is zeroed 
out or null, the name of the site managing the current working directory is used. 
Pointer to the Account Code associated with the given Account Name. 


2.1.5. hpss_BeginExTrans 

Purpose 

Begin an HPSS extended transaction. 

Synopsis 

#include "hpss api.h" 
int 

hpssBeginExT r ans( 

hpss uuid t * CoreServerUUID); /* IN */ 

Description 

This routine will begin an HPSS extended transaction for the specified Core Server. All transaction 
enabled APIs will be made within the current transaction for the thread. A transaction begun by this 
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routine will remain current for the thread until an hpss_EndExTrans() call is issued from the same thread. 

Parameters 

CoreServerUUID Core Server UUID. 

Return Values 

Upon successful completion, hpssBeginExTrans returns zero. Otherwise, hpssBeginExTrans returns a 
negative value, the absolute value of which indicates the specific error. 

Error Conditions 

EINVAL 
ENOTDIR 

See Also 

hpssEndExT rans 

Notes 

None. 

2.1.6. hpss_Chacct 

Purpose 

Change the account code of an HPSS file. 

Synopsis 

#include "hpssapi.h" 
int 

hpss_Chacct( 

char *Path, 

acct rec t AcctCode ); 

Description 

The hpss_Chacct routine changes the accounting code for the file or directory named by Path. 

Parameters 

Path Names the file for which the account code is being changed. 

AcctCode Specifies the new accounting code for the file. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which indicates the specific error. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix. 

EFAULT The Path parameter is a NULL pointer. 


/* IN */ 
/* IN */ 


CoreServerUUID NULL. 

A non-DMGateway client issued the API. 
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ENAMETOOLONG 


The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 

EPERM The client does not have the appropriate privileges to perform the operation or is 

configured for Unix-style accounting. 

See Also 

hpssAcctCodeToName, hpssAcctNameToCode, hpssChacctByName, hpssGetAcct, 
hpssGetAcctName, hpssSetAcct, hpssSetAcctByName, hpssChown, hpssSetFileAttributes 

Notes 

None. 

2.1.7. hpss_ChacctByName 

Purpose 

Change the account code of an HPSS file or directory by specifying the account's name. 

Synopsis 

#include "hpss api.h" 
int 

hpssChacctByN ame( 

char -Path, /* IN */ 

char *AccountName ); /* IN */ 

Description 

The hpss ChacctByName routine changes the accounting code for the file or directory named by Path. 

Parameters 

Path Names the file or directory for which the account code is being changed. 

AccountName The account name corresponding to the new accounting code for the file or 

directory. 

Return Values 

Upon successful completion, a value of zero is returned . Otherwise, a negative value is returned, the 
absolute value of which indicated the specific error. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix. 

EFAULT The Path parameter is a NULL pointer or AcctName is NULL. 

EINVAL The specified AccountName is not a valid account name. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 


HPSS Programmer's Reference 
Release 6.2 (Revision 2.0) 


July 2008 


33 



ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 

EPERM The client does not have appropriate privilege to perform the operation or is 

configured for Unix-style accounting. 


See Also 


hpssGetAcct, hpssSetAcct, hpssChown, hpssSetFileAttributes, hpssGetAcctName, 
hpssSetAcctByName, hpssChacct 


None. 

2.1.8. hpss_Chdir 

Purpose 

Change current working directory. 

Synopsis 

#include “hpss api.h” 
int 

hpss_Chdir( 

char *Path ); /* IN */ 


Description 

The hpss_Chdir function changes a thread’s current working directory to be the directory named by Path. 

Parameters 

Path Specifies path name of the directory to which the current working directory is 

to be changed. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX. 1 chdir. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix. 

EFAULT The Path parameter is a NULL pointer. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 

component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 

See Also 

hpss Getcwd, hpss Chroot. 
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Notes 


None. 

2.1.9. hpss_Chmod 

Purpose 

Change the file mode of an HPSS file. 

Synopsis 

#include "hpssapi.h" 
int 

hpss_Chmod( 

char *Path, /* IN */ 
mode t Mode); /* IN */ 

Description 

The hpss_Chmod function alters the file mode associated with file named by Path. 

Parameters 

Path Points to the path name of the file for which the file mode is being changed. 

Mode Specifies the new value to which the file mode is to be set. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX. 1 chmod. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix. 

EFAULT The Path parameter is a NULL pointer. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 

component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 

EPERM The client does not have the appropriate privileges to perform the operation. 

See Also 

hpss Chown, hpssStat, hpss FileGetAttributes, hpss FileSetAttributes. 

Notes 

None. 

2.1.10. hpss_Chown 

Purpose 
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Change owner and group of an HPSS File. 

Synopsis 

#include "hpss_api.h 
int 

hpss_Chown( 

char *Path, 
uid_t Owner, 
gid_t Group ); 

Description 

The hpss_Chown function sets the user ID and group ID of the file named by Path to the values specified 
by Owner and Group, respectively. 

Parameters 

Path Names the file for which the owner and group owner are being changed. 

Owner Specifies the new value for the owner of the file. 

Group Specifies the new value for the group owner of the file. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX. 1 chown. If the owner is changed, the 
account code of the file or directory will also be changed to reflect that configured for the new owner. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix. 

EFAULT The Path parameter is a NULL pointer. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 

EPERM The client does not have the appropriate privileges to perform the operation. 


/* IN */ 
/* IN */ 
/* IN */ 


See Also 


hpssChmod, hpss Stat, hpss FileGetAttributes, hpss FileSetAttributes. 

Notes 


None. 

2.1.11. hpss_Chroot 

Purpose 

Change the root directory for the current client. 
Synopsis 
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#include "hpss_api.h" 
int 

hpss_Chroot( 

char *Path ); /* IN */ 


Description 

The hpss_Chroot function changes the root directory for the current client. After a successful call to 
hpss_Chroot, all absolute path name operations are done relative to Path, and relative operations cannot be 
made out of the subtree whose root is Path. 

Parameters 

Path Specifies the path name of the directory that is to become the new root 

directory. 


Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix. 

EFAULT The Path parameter is a NULL pointer. 

EINVAL This call was made from the nonglobal Client API library. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 


See Also 


hpss Chdir, hpss Getcwd. 

Notes 


Note that as currently implemented, symbolic links could allow a client to access files outside the new root 
directory (since hpss_Chroot bookkeeping is maintained entirely in the client API but symbolic links are 
generally handled in the Core Server). If this is a problem (the only current projected client is the FTP 
server for anonymous FTP), changes could be made to ensure that the symbolic links do not access files 
outside the subtree - failing if they do, or possibly traversing the symbolic link contents within the client 
API. 

2.1.12. hpss_ClientAPIInit 

Purpose 

Initialize the Client API for the current thread. This is usually done automatically during the first Client API 
call made. However, it may also be performed separately, before other Client API calls. 

Synopsis 

#include "hpss_api.h" 
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int 

hpss_ClientAPIInit( 

apithrdstate_t **ThreadContext ) ; /* OUT */ 


Description 

If the thread’s state has already been initialized just return a pointer to the thread’s specific state. Otherwise 
initialize and connect to all necessary servers and then return the new thread specific state. 

Parameters 


ThreadContext 

Return Values 

0 

Error Conditions 

ENOCONNECT 

ENOMEM 

EPERM 

See Also 

None. 

Notes 

None. 


Thread’s specific state 


No error. Thread specific state is valid. 


Could not initialize HPSS connection services. 
Memory allocation failed. 

Could not initialize security. 


2.1.13. hpss_ClientAPIReset 

Purpose 

Reset the current Client API control information. 

Synopsis 

#include "hpss_api.h" 
void 

hpss_ClientAPIReset(void); 

Description 

The hpss_ClientAPIReset routine will clean up the current Client API control information, including 
closing server connections. The next Client API call should then reinitialize the control information based 
on the current configuration information. 

Parameters 

None. 

Return Values 

None. 
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Error Conditions 


None. 


See Also 


hpss GetConiiguration, hpss SetConiiguration. 

Notes 


None. 

2.1.14. hpss_Close 

Purpose 

Close a file. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Close( 

int Fildes ); /* IN */ 


Description 

The hpss_Close function terminates the connection between the file handle, Fildes, and the file to which it 
is associated. The file handle and any associated resources are deallocated and can be reused by a 
subsequent call to hpss_Open. 

Parameters 

Fildes Specifies the file handle obtained from a previous hpss_Open. 

Return Values 

Upon successful completion, hpss_Close returns zero. Otherwise, hpss_Close returns a negative value; the 
absolute value of which is equal to an ermo value set by POSIX. 1 close. 

Error Conditions 

EBADF 
EBUSY 

See Also 

hpssOpen 

Notes 

None. 

2.1.15. hpss_Closedir 

Purpose 

Close an open directory stream. 


The specified file descriptor is out of range, or does not refer to an open file. 
The file is currently in use by another client thread. 

, hpss OpenBitfile, hpss ReopenBitfile. 
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Synopsis 

#include "hpss_api.h" 
int 

hpss_Closedir( 

int Dirdes ); /* IN */ 


Description 

The hpss_Closedir function closes the directory stream corresponding to the open directory stream handle 
Dirdes. 

Parameters 

Dirdes Specifies the open directory stream handle corresponding to the stream to be 

closed. 


Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX.l closedir. 

Error Conditions 

EBADF The specified directory descriptor does not refer to an open directory. 

EBUSY The directory is currently in use by another client thread. 

See Also 


hpssOpendir. 

Notes 


None. 

2.1.16. hpss_ConvertldsToNames 

Purpose 

Convert UIDs to user names, GDDs to group names, and/or realm IDs to realm names. 

Synopsis 

int 

hpss_ConvertIdsToNames( 

signed32 NumEntries, /* IN */ 

api_namespec_t *Specs ); /* IN/OUT */ 


Description 

The hpss ConvertldsToNames function converts a batch of Unix UIDs to user names, GIDs to group 
names, and/or realm ids to realm names. Each entry in the Specs array tells what kind of translation is 
needed for that entry. 

Parameters 

NumEntries Number of entries in the Specs array. 
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Specs Pointer to an area that contains information for defining a principal, which is to 

be converted, and the results of the conversion. 

Return Values 

Upon successful completion this routine returns zero. Otherwise it returns an error value describing the 
problem. 

Error Conditions 

EINVAL The Specs array has an entry that contains a zero realm id. 

ENOCONNECT A problem with the security registry. 

EFAULT A name is too long to fit into Specs. 

EAGAIN Default for security registry error. 

See Also 

hpssConvertN amesToIds 

Notes 


1. The Specs array must contain NumEntries elements of type api name spec_t. Each array element has a 
Type field that determines how the element will be translated. If the Type is NAMESPECSKIP, then 
the Id and Realmld fields will be ignored, and the Name and RealmName fields will be set to undefined 
values. NAMESPEC SKIP enables ACL editors to deal with ACL entry types, such as the mask object, 
which do not contain any ids. 

2. If the Type is set to NAMESPEC REALM, then the Realmld field will be translated into a realm name, 
which is returned in the RealmName field. In this case, the Id field will be ignored and the Name field 
will be set to an undefined value. On the other hand, if the Type is set to NAMESPECUSER or 
NAMESPEC GROUP, then the function returns the user or group name in the Name field as well as 
filling in the RealmName field. 

3. If, at any point during the translation process, an array entry is found that cannot be translated, the 
routine will return immediately. In this case, the Name and RealmName fields of each Specs array entry 
should be considered undefined, but the Type, Id and Realmld fields will remain unchanged from their 
initial values. Therefore the caller may need to keep a copy of the Specs array if the name fields will be 
needed again. 

4. If the principal cannot be found in the desired realm, then the routine does not return an error, but rather 
just stores an ASCII representation of the principal’s id in the Name field. Likewise, if the realm cannot 
be found in the trusted realm table, then the routine returns the realm id in the RealmName field. This 
allows the caller to deal with principals and/or realms that no longer exist. The caller may detect this 
“error” by scanning for numeric data in these fields. 

2.1.17. hpss_ConvertNamesTolds 

Purpose 

Convert user names to UIDs, group names to GIDs , and/or realm names to realm IDs. 

Synopsis 

int 

hpss_ConvertNamesToIds( 
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signed32 NumEntries, /* IN */ 

api_namespec_t *Specs ); /* IN/OUT */ 


Description 

The hpssConvertNamesToIds function converts an array of user names to UIDs, group names to GIDs, 
and/or realm names to realm IDs. Each entry in the Specs array tells what kind of translation is needed for 
that entry. 

Parameters 

NumEntries Number of entries in the Specs array. 

Specs Pointer to an area that contains information for defining a principal, which is to 

be converted, and the results of the conversion. 


Return Values 

Upon successful completion this routine returns zero. Otherwise it returns an error value describing the 
problem. 

Error Conditions 

ENOENT One or more entries in the Specs array specified a principal or realm name that 

could not be found. 

ENOCONNECT A problem with the security registry. 

EINVAL Non-numeric principal id was specified. 


See Also 


hpssConvertldsT oN ames 

Notes 


1. The Specs array must contain NumEntries elements of type api name spec_t. Each array entry has a 
Type field that determines how that element will be translated. If the element’s Type is 
NAMESPEC SKIP, then the Name and Realm/Vawe fields will be ignored and the Id and Realmld 
fields will be set to undefined values. This is used to help ACL editors deal with ACL entry types, such 
as the mask object, which do not contain any names. 

2. If the element’s Type is set to NAMESPECREALM, the RealmName field is translated into a realm id, 
which is returned in the Realmld field. In this case, the Name field will be ignored and the Id field will 
be set to an undefined value. On the other hand, if Type is set to NAMESPECUSER or 
NAMESPEC GROUP, the function returns the UID or GID in the Id field as well as filling in the 
Realmld field. If the element’s Name and/or RealmName fields are strings or digits, the routine does not 
try to verify that the principal and/or realm actually exist. Rather, it just returns the corresponding 
values in the Id and Realmld fields. This allows the caller to deal with principals and/or realms that no 
longer exist. In this situation, the routine does not return ENOENT. 

3. If at any point during the translation process, an array entry is found that cannot be translated, the 
routine will return immediately. In this case, the Id and Realmld fields of each Specs array entry should 
be considered undefined, but the Type, Name, and RealmName fields will remain unchanged from their 
initial values. Therefore the caller may need to keep a copy of the Specs array if the id fields will be 
needed again. 
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2.1.18. hpss_CopyFile 

Purpose 

Copy an HPSS file. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_CopyFile( 

int SrcFiledes, /* IN */ 

int DestFiledes) /* IN */ 


Description 

The hpss_CopyFile function copies source file to destination file. 

Parameters 

SrcFiledes File descriptor of open source file. 

DestFiledes File descriptor of open destination file. 

Return Values 

Upon successful completion, hpss_CopyFile returns zero. Otherwise a negative value is returned; the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EBADF 

EBUSY 
EIO 

ENOTSUP 
ESTA TE 

See Also 

hpssOpen 

Notes 

None. 

2.1.19. hpss_Creat 

Purpose 

Create an HPSS file and open it for writing. 

Synopsis 

#include "hpss_api.h" 
int 


Source or destination file descriptors out of range (i.e. negative) or not HPSS 
type file descriptors, or the destination file was not opened for writes. 

Another thread is currently manipulating the destination file. 

An internal HPSS error has occurred. 

Source and destination files not owned by same Core Server. 

Connection for destination file no longer valid. 
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hpss_Creat( 

char *Path, 

mode_t Mode, 

hpss_cos_hints_t *HintsIn, 

hpss_cos_priorities_t *H±ntsPr±, 
hpss_cos_hints_t *H±ntsOut ); 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 


Description 

The hpss_Creat function calls hpss_Open with the Oflag parameter defined as O WRONLY \ O CREAT \ 
O TRUNC. It creates a new file or rewrites an existing one. The newly created or previously existing file 
is opened for writing (see hpss_Open). 

Parameters 


Path Names the file to be opened or created. 

Mode Specifies the file permission. 

Hintsln Points to an hpss_cos_hints_t structure which provides allocation hints to 

HPSS as to the expected structure or access of the file. This argument may be 
NULL pointer if the default COS is to be used. 

HintsPri Points to an hpss_cos_priorities_t structure which provides the relative 

priorities associated with the fields contained in the Hintsln structure. This 
argument may be a NULL pointer and the priority will be set to 
REQUIREDPRIORITY. 

HintsOut Points to an hpss_cos_hints_t structure which will contain the values actually 

used when the file is created. This argument may be a NULL pointer if the 
returned values are to be ignored. 

Return Values 


Upon successful completion, hpss_Creat returns a file descriptor. Otherwise, it returns a negative value; 
the absolute value of which is equal to an ermo value (see hpss_Open). 

Error Conditions 

See hpss_Open for error conditions. 

See Also 


hpss Open, hpss Umask. 

Notes 

The hpss_Creat function mimics the POSIX creat function. It opens the file for writing and returns a file 
descriptor. 

2.1.20. hpss_Create 

Purpose 

Create an HPSS file. 

Synopsis 

#include "hpss_api.h" 
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int 

hpss_Create( 


char 

*Path, 

/* 

IN 

*/ 

mode_t 

Mode, 

/* 

IN 

*/ 

hpss_cos_hints_t 

*HintsIn, 

/* 

IN 

*/ 

hpss_cosj?riorities_t 

*HintsPri, 

/* 

IN 

*/ 

hpss_cos_hints_t 

*HintsOut ) ; 

/* 

OUI 

• *> 


Description 

The hpss_Create function creates the specified file, if it does not already exist. The newly created or 
previously existing file is not opened (see hpss_Open). 

Parameters 


Path Names the file to be opened or created. 

Mode Specifies the file permission. 

Hintsln Points to an hpss_cos_hints_t structure which provides allocation hints to 

HPSS as to the expected structure or access of the file. This argument may be 
NULL pointer if the default COS is to be used. 

HintsPri Points to an hpss_cos_priorities_t structure which provides the relative 

priorities associated with the fields contained in the Hintsln structure. This 
argument may be a NULL pointer and the priority will be set to 
REQUIREDPRIORITY. 

HintsOut Points to an hpss_cos_priorities_t structure which provides the relative 

priorities associated with the fields contained in the Hintsln structure. This 
argument may be a NULL pointer and the priority will be set to 
REQUIREDPRIORITY. 

Return Values 


Upon successful completion, hpss_Create returns zero. Otherwise, hpss_Create returns a negative value; 
the absolute value of which is equal to an ermo value defined below. 


Error Conditions 


EACCES Search permission is denied on a component of the Path prefix or the file does 

not exist and write permission is denied for the parent directory of the file to be 
created. 

EAGAIN Gatekeeper retries have timed out. 

EEX1ST The named file exists. 

EFAULT Path is NULL. 

EINVAL One or more values in the Hintsln parameter is invalid. 

ENAMETOOLONG The length of the Path string exceeds the system-imposed path name limit or a 
path name component exceeds the system-imposed limit. 

ENOENT Path is an empty string. 

ENOMEM Memory could not be allocated for path name. 

ENOTDIR A component of the Path prefix is not a directory. 
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See Also 


hpss Open, hpssUmask. 

Notes 


The hpss_Create function differs from the POSIX creat in that no attempt is made to open the file and it 
behaves as if the OEXCL flag was set (see EEXIST, above). 


2.1.21. hpss_CreateDMHandle 

Purpose 

Create an HPSS DMAP file. 


Synopsis 


#include "hpss_api.h" 
int 

hpss_CreateDMHandle( 
ns_Obj Handle_t 
char 
mode_t 
sec_cred_t 
hpss_cos_hints_t 
hpss_cosj?riorities_t 
unsigned32 
hpss_cos_hints_t 
hps s_vattr_t 
hps s_authz_token_t 


ObjHandle , 

*Path, 

Mode, 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
*/ 
*/ 
*/ 

OUT */ 


*Ucred, 

*HintsIn, 

*HintsPr± 

ConsistencyFlags, /* IN 

*HintsOut, /* OUT 

*AttrsOut, /* OUT 

* AuthzTicket) /* 


Description 

The hpss_CreateDMHandle function creates a DMAP file specified by 'Path', with permissions as 
specified by 'Mode' and using the class of service values specified by 'Hintsln' and 'HintsPri', if non-NULL. 

Parameters 


ObjHandle 

Path 

Mode 

Ucred 

Hintsln 


HintsPri 


ConsistencyFlags 

HintsOut 


NS object handle of parent directory of Path. 

Names the file to be opened or created. 

Specifies the file mode used for determining the mode for the created file. 
Pointer to structure containing the user credentials for the new file. 

Points to an hpss_cos_hints_t structure which provides allocation hints to 
HPSS as to the expected structure or access of the file. This argument may be 
NULL pointer if the default COS is to be used. 

Points to an hpss_cos_priorities_t structure which provides the relative 
priorities associated with the fields contained in the Hintsln structure. This 
argument may be a NULL pointer and the priority will be set to 
REQUIREDPRIORITY. 

Core Server consistency flags to use for the new file. 

Points to an hpss_cos_hints_t structure which will contain the values actually 
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used when the file is created. This argument may be a NULL pointer if the 
returned values are to be ignored. 

AttrsOut Pointer to structure containing the attributes for the new file. 

AuthzTicket Pointer to structure containing a client authorization ticket for the new file. 

Return Values 

Upon successful completion, hpss_CreateDMHandle returns zero. Otherwise, a negative value is 
returned; the absolute value of which is equal to an ermo value defined below. 

Error Conditions 


EACCES 

EAGAIN 

EEXIST 

EFAULT 

EINVAL 

ENAMETOOLONG 

ENOENT 

ENOSPC 

ENOTDIR 

See Also 

hpssCreate 

Notes 

None. 


Search permission is denied on a component of the Path prefix or the file does 
not exist and write permission is denied for the parent directory of the file to be 
created. 

Gatekeeper retries have timed out. 

The named file exists. 

Path is NULL. 

One or more values in the Hintsln parameter is invalid or the ObjHandle is 

The length of the Path string exceeds the system-imposed path name limit or a 
path name component exceeds the system-imposed limit. 

Path points to a zero value. 

Resources could not be allocated for the new file. 

A component of the Path prefix is not a directory. 


2.1.22. hpss_CreateHandle 

Purpose 

Create an HPSS file. 


#include "hpss_api.h" 
int 

hpss_CreateHandle( 

ns_ObjHandle_t ObjHandle , /* IN */ 

char *Path, /* IN */ 

mode_t Mode, /* IN */ 

sec_cred_t *Ucred, /* IN */ 

hpss_cos_hints_t *H±ntsIn, /* IN */ 

hpss_cosj?riorities_t *H±ntsPr±, /* IN */ 
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*H±ntsOut, 
*AttrsOut, 
*AuthzTicket) 


/* 

h 

h 


OUT 

OUT 

OUT 


7 

■7 

■7 


hpss_cos_hints_t 
hps s_vattr_t 
hps s_authz_token_t 


Description 

The hpss_CreateHandle function creates a file specified by 'Path', with permissions as specified by 'Mode' 
and using the class of service values specified by 'Hintsln' and 'HintsPri', if non-NULL. The newly created 
or previously existing file is not opened (see hpss_Open). 

Parameters 


ObjHandle 

Path 

Mode 

Ucred 

Hintsln 


HintsPri 


HintsOut 


AttrsOut 

AuthzTicket 


NS object handle of parent directory of Path. 

Names the file to be created. 

Specifies the file mode used for determining the mode for the created file. 

Pointer to an sec_cred_t structure containing the user credentials for the new 
fde. 

Points to an hpss_cos_hints_t structure which provides allocation hints to 
HPSS as to the expected structure or access of the fde. This argument may be 
NULL pointer if the default COS is to be used. 

Points to an hpss_cos_priorities_t structure which provides the relative 
priorities associated with the fields contained in the Hintsln structure. This 
argument may be a NULL pointer and the priority will set to 
REQUIREDPRIORITY. 

Points to an hpss_cos_hints_t structure which will contain the values actually 
used when the file is created. This argument may be a NULL pointer if the 
returned values are to be ignored. 

Pointer to an hpss_vattr_t structure containing the attributes for the new file. 

Pointer to an hpss_authz_token_t structure containing a client authorization 
icket for the new file. 


Return Values 

Upon successful completion, hpss_CreateHandle returns zero. Otherwise, a negative value is returned; the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 


EACCES Search permission is denied on a component of the Path prefix or the file does 

not exist and write permission is denied for the parent directory of the file to be 
created. 

EAGAIN Gatekeeper retries have timed out. 

EEXIST The named fde exists. 

EFAULT Path is NULL. 

EINVAL One or more values in the Hintsln parameter is invalid or the ObjHandle is 

NULL. 

ENAMETOOLONG The length of the Path string exceeds the system-imposed path name limit or a 
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path name component exceeds the system-imposed limit. 
ENOENT Path points to a zero value. 

ENOSPC Resources could not be allocated for the new file. 

ENOTDIR A component of the Path prefix is not a directory. 

See Also 

hpssCreate 

Notes 


None. 

2.1.23. hpss_CreateWithHints 

Purpose 

Create an HPSS file with specified COS and priority. 

Synopsis 

#include "hpss j?osix_api.h" 
int 

hpss CreateWithHints( 

IN */ 
IN */ 
IN */ 
IN */ 
OUT */ 


char *Path, /* 
mode_t Mode, /* 
hpss_cos_hints_t *H±ntsIn, /* 
hpss_cosj?riorities_t *H±ntsPr±, /* 
hpss_cos_hints_t *HintsOut); /* 


Description 

The hpss_CreateWithHints function creates a file specified by 'Path', with permissions as specified by 

'Mode' and using the class of service values specified by 'Hintsln' and 'HintsPri', if non-NULL. The newly 

created or previously existing file is not opened (see hpss_Open). 

Parameters 

Path Names the file to be created. 

Mode Specifies the file mode used for determining the mode for the created file. 

Hintsln Points to an hpss_cos_hints_t structure which provides allocation hints to 

HPSS as to the expected structure or access of the file. This argument may be a 
NULL pointer if the default COS is to be used. 

HintsPri Points to an hpss_cos_priorities_t structure which provides the relative 

priorities associated with the fields contained in the Hintsln structure. This 
argument may be a NULL pointer and the priority will set to 
REQUIREDPRIORITY. 

HintsOut Points to an hpss_cos_hints_t structure which will contain the values actually 

used when the file is created. This argument may be a NULL pointer if the 
returned values are to be ignored. 

Return Values 


HPSS Programmer's Reference 
Release 6.2 (Revision 2.0) 


July 2008 


49 



Upon successful completion, hpss_CreateWithHints returns zero. Otherwise, a negative value is returned; 
the absolute value of which is equal to an ermo value, as defined below. 

Error Conditions 


EACCES 

EAGAIN 

EEXIST 

EFAULT 

EINVAL 

ENAMETOOLONG 

ENOENT 

ENOMEM 

ENOTDIR 

See Also 

hpssCreate 

Notes 


Search permission is denied on a component of the Path prefix or the file does 
not exist and write permission is denied for the parent directory of the file to be 
created. 

Gatekeeper retries have timed out. 

The named file exists. 

Path is NULL. 

One or more values in the Hintsln parameter is invalid. 

The length of the Path string exceeds the system-imposed path name limit or a 
path name component exceeds the system-imposed limit. 

Path points to an empty string. 

Memory could not be allocated for the new psth name. 

A component of the Path prefix is not a directory. 


The hpss_CreateWithHints function is identical to hpss_Create. It is created at the request of a customer. 

2.1.24. hpss_DeleteACL 

Purpose 

Removes entries from the Access Control List of a file. 

Synopsis 

#include "hpss_api.h" 

int 

hpss_DeleteACL( 

char *Path, 

unsigned32 Options, 

ns_ACLConfArray_t *ACL ) ; 


/* IN */ 
/* IN */ 
/* IN */ 


Description 

The hpss_DeleteACL function removes the ACL entries specified by ACL from the file named by Path. 

Parameters 

Path Names the file for which the ACL is being removed. 

Options Bit vector used to specify what type of ACL is to be retrieved. One of: 

• HPSS ACL OPTION OBJ - return object's normal ACL. 
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HPSS ACL OPTION IO - return the initial-object ACL. (only valid 
for directory objects). 


• HPSS ACL OPTION IC - return the initial-container ACL. (only 
valid for directory objects). 

ACL Points to the list of ACL entries to be removed. 


Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned; the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 


EACCES 

EFAULT 

EINVAL 

ENAMETOOLONG 

ENOENT 

ENOTDIR 

EPERM 

ESRCH 


Search permission is denied on a component of the path prefix. 

The Path or ACL parameter is a NULL pointer. 

Exactly one of the HPSS ACL OPTION * bits must be set in the Options bit 
vector to avoid receiving this error. 

The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

The named file does not exist, or the Path argument points to an empty string. 
A component of the Path prefix is not a directory. 

The client does not have the appropriate privileges to perform the operation. 

A specified ACL entry did not match an existing ACL entry for the file. 


See Also 


hpssGetACL, hpss_SetACL,hpss_UpdateACL. 

Notes 


None. 

2.1.25. hpss_DeleteACLHandle 

Purpose 

Removes entries from the Access Control List of a file. 

Synopsis 

#include "hpss_api.h" 
int 

hpss DeleteACLHandle( 

*/ 
*/ 
*/ 
*/ 
*/ 


ns_ObjHandle_t ObjHandle, /* IN 
char *Path, /* IN 
sec_cred_t *Ucred, /* IN 
unsigned32 Options, /* IN 
ns_ACLConfArray_t *ACL ) ; /* IN 


Description 
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The hpss_DeleteACLHandle function removes an ACL entry from the Access Control List of a file or 
directory named by 'Path', taken relative to the directory indicated by ’ObjHandle'. 

Parameters 

ObjHandle Parent object handle. 

Path Names the file for which the ACL is being removed. 

Ucred User credentials. 

Options Bit vector used to specify what type of ACL is to be retrieved. One of: 

• HPSS ACL OPTION OBJ - return object's normal ACL. 

• HPSS ACL OPTION IO - return the initial-object ACL. (only valid 
for directory objects). 

• HPSS ACL OPTION IC - return the initial-container ACL. (only 
valid for directory objects). 

ACL Points to the list of ACL entries to be removed. 

Return Values 

Upon successful completion, a value of zero is relumed. Otherwise, a negative value is returned; the 
absolute value of which is equal to an ermo value defined below. 

Search permission is denied on a component of the path prefix. 

The Path or ACL parameter is a NULL pointer. 

Exactly one of the HPSS ACL OPTION * bits must be set in the Options bit 
vector to avoid receiving this error. 

The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

The named file does not exist, or the Path argument points to an empty string. 
A component of the Path prefix is not a directory. 

The client does not have the appropriate privileges to perform the operation. 

A specified ACL entry did not match an existing ACL entry for the file. 

SetACL,hpss_UpdateACL. 


2.1.26. hpss_EndExTrans 

Purpose 

End an HPSS extended transaction. 

Synopsis 


Error Conditions 

EACCES 

EFAULT 


EINVAL 

ENAMETOOLONG 

ENOENT 

ENOTDIR 

EPERM 

ESRCH 


hpss GetACL, hpss_ 
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#include "hpssapi.h" 
int 

hpssEndExTrans) 

hpssExTransOutcomet Outcome) /* IN */ 

Description 

This routine will end the current HPSS extended transaction for the thread. 

Parameters 

Outcome Desired transaction outcome (Abort or Commit). 

Return Values 

Upon successful completion, hpssEndExTrans returns zero. Otherwise, hpssEndExTrans returns a 
negative value, the absolute value of which indicates the specific error. 

Error Conditions 

EINVAL Invalid Outcome specified. 

ENOENT No current transaction for the thread. 

ENOTSUP A non-DMAP Gateway client issued the API. 

See Also 

hpssBeginExT r ans 

Notes 


2.1.27. hpss_Fclear 

Purpose 

Clear part of a file. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Fclear ( 

int Fildes, /* IN */ 

u_signed64 Length ); /* IN */ 


Description 

The hpss_Fclear routine clears part of an open file, specified by Fildes, the current file offset and Length. 
A hole will be created in the file covering the part of the file that was cleared, and its storage resource may 
be freed accordingly. 

Parameters 

Fildes Specifies the file descriptor identifying the open file for which part is to be 

cleared. 
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Length Specifies the number of bytes to be cleared. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EBADF The specified file descriptor does not correspond to a file opened for writing. 

EBUSY The specified file descriptor is currently in use. 

See Also 


hpssFclearOffset, hpss Truncate, hpss Ftruncate. 

Notes 


2.1.28. hpss_FclearOffset 

Purpose 

Clear part of a file beginning at the specified offset. 

Synopsis 

#include "hpss_api.h" 

int 

hpss_FclearOffset( 

int Fildes, /* IN */ 

u_signed64 Offset, /* IN */ 

u_signed64 Length ); /* IN */ 


Description 

The hpss_FclearOffset routine clears part of an open file, specified by Fildes, the current file Offset, and 
Length. A hole will be created in the file covering the part of the file that was cleared, and storage 
resources may be freed accordingly. 

Parameters 

Fildes Specifies the file descriptor identifying the open file of the part to clear. 

Offset Specifies where to begin clearing the file. 

Length Specifies the number of bytes to be cleared. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EBADF The specified file descriptor does not correspond to a file opened for writing. 
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EBUSY 
EINVAL 

See Also 

hpssFclear 

Notes 

None. 

2.1.29. hpss_Fclose 

Purpose 

Close an HPSS Stream. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Fclose( 

HPSS_FILE *hpss_Stream); /* IN */ 

Description 

The hpss_Fclose routine flushes any buffered data to the open HPSS stream, then closes the HPSS file. 

Parameters 

hpss Stream The open HPSS Stream pointer. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EBADF Invalid file descriptor or file not open. 

EFAULT Invalid or NULL pointer. 

EBUSY HPSS file table entry busy. 

ESTALE Stale connection. 

EIO Internal error condition. 

See Also 

hpssFflush 

Notes 

None 


The specified file descriptor is currently in use. 
The Length or Offset argument is invalid. 
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2.1.30. hpss_Fcntl 

Purpose 

Control HPSS open file descriptors. 
Synopsis 

#include "hpss_api.h" 
int 

hpss_Fcntl( 


int 

hpss fd, 

/* 

IN 

*/ 

int 

Cmd, 

/* 

IN 

*/ 

long 

Arg) ; 

/* 

IN 

*/ 


Description 

This function will accept the following commands in the Cmd argument and perform the indicated actions: 

F GETFL Get the 0_N0NBL0CK flag for an open file. 

FSETFL Set the ONONBLOCK flag for an open file. 

FHPSSSETCOS Set the the class of service for the open file. 

FHPSSSETFILESIZE Set the open FIPSS file to the appropriate COS based on size of file given by 
'Arg'. 

Parameters 

hpssJ'd The open HPSS file descriptor. 

Cmd The input command to be invoked (see above). 

Arg The argument of the 'Cmd' parameter: 

FGETFL/FSETFL - N/A 
F HPSS SET COS - The COS identifier 
F HPSS SET FILE SIZE - Size of file in bytes. 

Return Values 

If the F GETFL/F SETFL command is successful, the file's O NONBLOCK flag will be returned. For the 
other commands, a zero will be returned if the command is successful. Otherwise, a negative value will be 
returned indicating the error encountered: 

Error Conditions 


EBADF 

EFAULT 

EBUSY 

ESTALE 

ENOTSUP 


See Also 


Invalid file descriptor or file not open. 
Invalid object handle. 

HPSS file table entry busy. 

Stale Connection. 

Command not supported. 
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None 


Notes 

None 

2.1.31. hpss_Fflush 

Purpose 

Flush an HPSS stream. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Fflush( 

HPSS_FILE *hpss_Stream); /* IN */ 

Description 

The 'hpss_Fflush' function writes any buffered data for the stream specified by the hpssStream parameter, 
leaving the stream open. 

Parameters 

hpss Stream The open HPSS stream pointer. 

Return Values 

If the operation is successful, a zero value is returned. Otherwise, a negative value is returned whose 
absolute value indicates the error as listed below. 

Error Conditions 

EBADF Invalid file descriptor or file not open. 

EINVAL Invalid or NULL input parameter. 

EBUSY HPSS file table entry busy. 

ESTALE Stale Connection. 

EIO An internal error has occurred. 

See Also 

hpss Fopen, hpss Fclose, hpss Fread, hpss Fwrite, hpss Fseek, hpss Ftell 

Notes 

None 

2.1.32. hpss_Fgetc 

Purpose 

Read a single character from an open file. 

Synopsis 
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#include "hpss_api.h" 
int 

hpss_Fgetc( 

HPSS_FILE* *stream) /* IN */ 


Description 

The hpss_Fgetc function returns the next character in the open file stream. 

Parameters 


Stream The open HPSS Stream pointer. 

Return Values 

Upon successful completion, the value of the next character in the file is returned. EOF is returned if the 
end of the file is reached. The global ermo vaue wll be set to a non-zero value if an error condition occurs. 

Error Conditions 


EBADF 

EINVAL 

EFAULT 

EBUSY 

ESTA TE, 

EPERM 


See Also 


Invalid file descriptor or file not open. 

Invalid input parameter (Ptr Null or Size zero) 

NULL stream pointer. 

HPSS file table entry busy. 

Stale Connection. 

File opened for write only or trying to read after a write without a file 
positioning operation. 


hpss Fseek, hpss_Fflush,hpss_Fwrite, hpss Fopen, hpss Fclose, hpss Ftell, hpssFgets 


Notes 


The behavior of this function is modeled after the system fgetcQ routine. 


2.1.33. hpss_Fgets 

Purpose 

Read a string from an open stream. 

Synopsis 

#include "hpss_api.h" 
char* 

IN/OUT */ 
IN */ 

IN */ 


char* 

int 

HPSS FILE* 


Description 
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The hpss_Fgets function returns the a string from the open file stream, up to n characters or a newline. 

Parameters 

s The buffer for the string data. 

n The maximum number of bytes to read. 

Stream The open HPSS Stream pointer. 

Return Values 

Upon successful completion, a string of n or less bytes is returned. hpss Fgets will stop return a string of 
less than n bytes when a newline is reached. If EOF is reached, NULL is returned. 

Error Conditions 

EBADF Invalid file descriptor or file not open. 

EINVAL Invalid input parameter (Ptr Null or Size zero) 

EFAULT NULL stream pointer. 

EBUSY HPSS file table entry busy. 

ESTALE Stale Connection. 

EPERM File opened for write only or trying to read after a write without a file 

positioning operation. 

EIO More than n bytes were read. 

See Also 

hpss Fseek, hpss_Fflush,hpss_Fwrite, hpss Fopen, hpss Fclose, hpss Ftell, hpssFgetc 

Notes 


The behavior of this function is modeled after the system fgets() routine. 

2.1.34. hpss_FileGetAttributes 

Purpose 

Get attributes for a file. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_FileGetAttributes( 

char *Path, /* IN */ 

hpss_fileattr_t *AttrOut ) ; /* OUT */ 


Description 

The hpss_FileGetAttributes function returns the file attribute structure for the file named by Path. The 
attributes are returned in the structure pointed to by AttrOut. 

Parameters 
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Path Points to the path name of the file being queried. 

AttrOut Points to the structure that will hold the file attributes. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which indicates the specific error. 

Error Conditions 

EACCES Search permission is denied for a component of the path prefix. 

EFAULT The Path or AttrOut parameter is a NULL pointer. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 

component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string.. 

ENOTDIR A component of the Path prefix is not a directory. 

See Also 

hpssFileGetAttributesHandle, hpssFileSetAttributes, hpssStat, hpssFstat, hpssLstat, 
hpssGetListAttrs, hpssReadAttrs. 

Notes 


The hpss_FileGetAttributes function reads through symbolic links and junctions. It cannot be used to get 
the attributes of the symbolic link or junction itself. 


2.1.35. hpss_FileGetAttributesHandle 

Purpose 

Get attributes for a file. 

Synopsis 


/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 
/* OUT */ 


#include "hpss_api.h" 
int 

hpss_FileGetAttributesHandle( 

ns_Obj Handle_t *ObjHandle, 

char *Path, 

sec_cred_t *Ucred, 

hpss_authz_token_t *AuthzTicket, 

hpss_fileattr_t *AttrOut ); 


Description 

The hpss FileGetAttributesHandle function can be used to query attributes on an entry in the name or file 
system that is referred to by ObjHandle and Path. The file attributes are returned in the AttrOut parameter. 

Parameters 

ObjHandle Pointer to parent object. 

Path Points to the path name of the file being queried. 
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Ucred 

AuthzTicket 

AttrOut 


User credentials. 

Authorization ticket. 

Points to the structure that will hold the file attributes. 


Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which indicates the specific error. 

Error Conditions 

EACCES Search permission is denied for a component of the path prefix. 

EFAULT The Path or AttrOut parameter is a NULL pointer. 

EINVAL ObjHandle is NULL. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 


hpssFileGetAttributes, hpssFileSetAttributes, hpssStat, hpss Fstat, hpss Lstat, 
hpssGetListAttrs, hpssReadAttrs. 


Notes 


None. 

2.1.36. hpss_FileGetAttributesSOID 

Purpose 


Get attributes for an FIPSS bitfile. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_FileGetAttributesSOID( 

hpssoid_t *B±tf±leID, 

char *Path, 

hpss_fileattr_t *AttrOut ); 


/* IN */ 
/* IN */ 
/* OUT */ 


Description 

The hpss FileGetAttributesSOID function can be used to query attributes on an entry in the name or file 
system that is referred to by BitfilelD. It returns one of possibly multiple path names to the bitfile and the 
file attributes structure for the bitfile. 

Parameters 

BitfilelD Pointer to bitfile ID. 


HPSS Programmer's Reference 
Release 6.2 (Revision 2.0) 


July 2008 


61 




Path 

AttrOut 


Pointer to the path name of the bitfile being queried. 
Pointer to the structure that will hold the file attributes. 


Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which indicates the specific error. 

Error Conditions 

EACCES Search permission is denied for a component of the path prefix. 

EFAULT The Path or AttrOut parameter is a NULL pointer. 

EINVAL BitfilelD is a NULL pointer. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 


hpssFileGetAttributes, hpssFileGetAttributesHandle, hpssFileSetAttributes, hpssStat, 
hpssFstat, hpss Lstat, hpssGetListAttrs, hpssReadAttrs. 


Notes 


None. 


2.1.37. hpss_FileGetXAttributes 

Purpose 

Get extended attributes for a file. 


Synopsis 


#include "hpss_api.h" 
int 

hpss_FileGetXAttributes 

char 

unsigned32 

unsigned32 

hpss_xfileattr_t 


( 

*Path, 

Flags, 

StorageLevel, 
*AttrOut ) ; 


/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 


Description 

The hpss_FileGetXAttributes function returns the file extended attribute structure for the file named by 
Path. The file may currently be open, but is not required to be open. The attributes are returned in the 
structure pointed to by AttrOut. 

Parameters 

Path Points to the pathname of the file being queried. 
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Flags 


StorageLevel 

AttrOut 


Specifies the flag that indicates the behavior of the call. The acceptable values 
are: 

APIGETSTATSFORLEVEL - Returns bitfile attributes at the storage 
level specified by the StorageLevel argument. 

APIGETSTATSFORISTLEVEL - Returns bitfile attributes at the first 
storage level whether or not it contains bitfile data. 

APIGETSTATSFOROPTIMIZE - Returns only Stripe Width and 
OptimumAccessSize for storage level zero. 

API GET STATS FOR ALL LEVELS - Returns bitfile attributes across all 
storage class levels. 

Specifies the specific storage level to query when the 
API GET STATS FOR LEVEL flag is used. 

Points to the structure that will hold the file attributes. 


Return Values 

Upon successful completion, a value of zero is returned . Otherwise, a negative value is returned, the 
absolute value of which indicates the specific error. 

Error Conditions 

EACCES Search permission is denied for a component of the path prefix. 

EFAULT The Path or AttrOut parameter is a NULL pointer. 

EINVAL BitfilelD is a NULL pointer. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 

component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 


See Also 


hpss FileSetAttributes, hpss FileSetAttributesHandle, hpss FileSetAttributesSOID, hpss Stat, 
hpss Fstat, hpss Lstat, hpss GetListAttrs, hpss ReadAttrs. 


Notes 

The hpss_FileGetXAttributes function reads through symbolic links and junctions and cannot be used to 
get the attributes of the symbolic link or junction itself. 

This call allocates memory for the returned physical volume conformant array. After the successful comple¬ 
tion of this call, the memory should be freed using code similar to the example below. 

for(i=0; i<HP S SMAXSTORAGELE VELS; i++) 

{ 

for(j=0;j<AttrOut.SCAttrib[i].NurnberOfVVs;j++) 

{ 

if (AttrOut. SCAttrib[i]. VVAttrib[j] .PVList != NULL) 
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free(AttrOut.SCAttrib[i]. WAttribU] .PVList); 


} 


2.1.38. hpss_FileSetAttributes 

Purpose 

Alter file attribute values. 


Synopsis 

#include "hpss_api.h" 
int 

hpss_FileSetAttributes( 
char 

hpss_fileattrbits_t 

hpss_fileattr_t 

hpss_fileattr_t 


*Path, 

SelFlags, 

*AttrIn, 

*AttrOut ) ; 


/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 


Description 

The hpss_FileSetAttributes function changes file attributes for the file named by Path, based on the 
attributes in the structure pointed to by Attrln. The updated file attributes after the completion of the 
request are returned in the structure pointed to by AttrOut. 

Parameters 

Path Points to the name of the file for which attribute values are to be changed. 

SelFlags Bitmask which indicates which attributes are to be set in the Core Server 

attributes. The following is a list of the file attributes that can be set using this 
function. 

COREATTRACCOUNT 

COREATTRCOMMENT 

COREATTRCOMPOSITEPERMS 

CORE ATTR COSJD 

COREATTRDATALENGTH 

COREATTRDMDATASTATEFLAGS 

COREATTRDMHANDLE 

CORE_ATTR_DM_HANDLE_LENGTHCORE_ATTR_DONT_PURGE 

COREATTRENTRYCOUNT 

COREATTREXTENDEDACLS 

COREATTRFAMILYID 

COREATTRFILESETHANDLE 

COREATTRFILESETID 

COREATTRFILESETROOTID 

COREATTRFILESETSTATEFLAGS 

COREATTRFILESETTYPE 
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COREATTRGATEWAYUUID 

COREATTRGIDCOREATTRGROUPPERMS 

COREATTRLINKCOUNT 

COREATTRMACSECLABEL 

COREATTROPENCOUNT 

COREATTROTHERPERMS 

COREATTRREADCOUNT 

COREATTRREALMID 

COREATTRREGISTERBITMAP 

CORE_ATTR_SET_GIDCORE_ATTR_SET_STICKY 

COREATTRSETUID 

COREATTRSUBSYSTEMID 

COREATTRTIMECREATED 

COREATTRTIMELASTREAD 

COREATTRTIMELASTWRITTEN 

CORE ATTR TIME MODIFIED 

COREATTRTYPE 

COREATTRUID 

COREATTRUSERPERMS 

COREATTRWRITECOUNT 

Attrln Points to a structure containing the new attribute values. 

AttrOut Points to a structure that will contain the file attribute values after completion 

of this request. 


Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which indicates the specific error. 

Error Conditions 


EACCES 

EFAULT 

EINVAL 

ENAMETOOLONG 

ENOENT 

ENOSPC 

ENOTDIR 

EOPNOTSUPP 

EPERM 

See Also 


Search permission is denied for a component of the path prefix. 

The Path, Attrln or AttrOut parameter is a NULL pointer. 

An attribute value or selection flag is invalid. 

The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

The named file does not exist, or the Path argument points to an empty string. 
Resources could not be allocated to satisfy the request. 

A component of the Path prefix is not a directory. 

The requested change is not supported. 

The client does not have the appropriate privileges to change the file's attributes. 


hpss FileGetAttributes, hpssFileGetAttributesHandle, hpss FileGetAttributesSOID, 
hpssFileSetAttributesHandle, hpssFileSetAttributesSOID, hpss Chown, hpss Chmod, hpss Utime. 


Notes 
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1. The Bitfile ID cannot be set using this function. 

2. The Account Code can be set only if site-style accounting is being used. 

3. A non-gateway client cannot specify both the Account Code and UID on the same call even if site-style 
accounting is being used. 

4. The contents of AttrOut will be zero upon return for a gateway client as the DMAP Gateway doesn't 
return any attributes. 

2.1.39. hpss_FileSetAttributesHandle 

Purpose 

Alter file attribute values. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_FileSetAttributesHandle( 

ns_ObjHandle_t ObjHandle, 

char *Path, 

sec_cred_t *Ucred, 

hpss_fileattrbits_t SelFlags, 

hpss_fileattr_t *AttrIn, 

hpss_fileattr_t *AttrOut ) 

Description 

The hpss FileSetAttributesHandle function can be used to change attributes on an entry in the name or 
file system that is referred to by Path and ObjHandle. 

Parameters 

ObjHandle Parent object handle. 

Path Points to the name of the file for which attribute values are to be changed. 

Ucred User credentials. 

SelFlags Bitmask which indicates which attributes are to be set in the Core Server 

attributes. Refer to hpss_FileSetAttributes for a list of attributes that can be 
set using this function. 

Attrln Points to a structure containing the new attribute values. 

AttrOut Points to a structure that will contain the file attribute values after completion 

of this request. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which indicates the specific error. 

Error Conditions 

EACCES Search permission is denied for a component of the path prefix. 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 
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EFAULT The Path, Attrln or AttrOut parameter is a NULL pointer. 

EINVAL An attribute value or selection flag is invalid, or the ObjHandle is NULL. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOSPC Resources could not be allocated to satisfy the request. 

ENOTDIR A component of the Path prefix is not a directory. 

EOPNOTSUPP The requested change is not supported. 

EPERM The client does not have the appropriate privileges to change the file's attributes. 


hpssFileGetAttributes, hpssFileGetAttributesHandle, hpssFileGetAttributesSOID, 
hpssFileSetAttributesHandle, hpssFileSetAttributesSOID, hpssChown, hpssChmod, hpssUtime. 


1. The Bitfile ID cannot be set using this function. 

2. The Account Code can be set only if site-style accounting is being used. 

3. A non-gateway client cannot specify both the Account Code and UID on the same call even if site-style 
accounting is being used. 

4. The contents of AttrOut will be zero on return for a gateway client as the DMAP Gateway doesn't return 
any attributes. 

2.1.40. hpss_FileSetAttributesSOID 

Purpose 

Alter file attribute values. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_FileSetAttributesSOID( 
hpssoid_t 

hpss_fileattrbits_t 
hpss_fileattr_t 
hpss_fileattr_t 
char 


*BitfileID, /* IN */ 


SelFlags, 
*Attrln, 

*AttrOut 
*Path) ; 


IN */ 
IN */ 
OUT */ 


Description 

The hpss FileSetAttributesSOID function can be used to set attributes on an entry in the name or file 
system that is referred to by BitfilelD. It returns one of possibly multiple path names to the bitfile in Path 
and the file attributes for the entry in AttrOut. 

Parameters 


HPSS Programmer's Reference 
Release 6.2 (Revision 2.0) 


July 2008 


67 



BitfilelD BitfilelD 

Path Points to the name of the file for which attribute values are to be changed. 

SelFlags Bitmask which indicates which attributes are to be set in the Core Server 

attributes. Refer to hpss_FileSetAttributes for a list of attributes that can be 
set using this function. 

Attrln Points to a structure containing the new attribute values. 

AttrOut Points to a structure that will contain the file attribute values after completion 

of this request. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which indicates the specific error. 

Error Conditions 

EACCES Search permission is denied for a component of the path prefix. 

EFAULT The AttrOut parameter is a NULL pointer. 

EINVAL An attribute value or selection flag is invalid, or BitfilelD is NULL. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOSPC Resources could not be allocated to satisfy the request. 

ENOTDIR A component of the Path prefix is not a directory. 

EOPNOTSUPP The requested change is not supported. 

EPERM The client does not have the appropriate privileges to change the file's attributes. 

See Also 

hpssFileGetAttributes, hpssFileGetAttributesHandle, hpssFileGetAttributesSOID, 
hpssFileSetAttributesHandle, hpssFileSetAttributesSOID, hpssChown, hpssChmod, hpssUtime. 

Notes 

1. The Bitfile ID cannot be set using this function. 

2. The Account Code can be set only if site-style accounting is being used. 

3. A non-gateway client cannot specify both the Account Code and UID on the same call even if site-style 
accounting is being used. 

4. The contents of AttrOut will be zero on return for a gateway client as the DMAP Gateway doesn't return 
any attributes. 

2.1.41. hpss_FilesetCreate 

Purpose 

Create an HPSS fileset. 
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Synopsis 

#include "hpss_api.h" 
int 

hpss_FilesetCreate( 
hpss_uuid_t 
unsigned32 

ns_FilesetAttrBits_t 
ns_FilesetAttrs_t 
hpss_AttrBits_t 
hps s_Attrs_t 
dmg_f i 1 e s e t_i n f o_t 
ns_FilesetAttrBits_t 
hpss_AttrBits_t 
ns_FilesetAttrs_t 
hps s_Attrs_t 
ns_Obj Handle_t 


* CoreServerUUID, 
CreateOptlons 
FilesetAttrBits, 

* FilesetAttrs, 
ObjectAttrBits, 
*ObjectAttrs, 
*DMGFSInfo 
RetFilesetAttrBits, 
RetObjectAttrBits, 
*RetF±lesetAttrs, 

* RetObjectAttrs, 

*FilesetHandle ); 


/* IN */ 

/* IN */ 

/* IN */ 

/* IN */ 

/* IN */ 

/* IN */ 

/* IN */ 

/* IN */ 

/* IN */ 

/* OUT */ 
/* OUT */ 
/* OUT */ 


Description 

The hpss_FilesetCreate function is called to create a new HPSS fileset. A handle to the newly created 
fileset is returned in the memory pointed to by FilesetHandle. 

Parameters 

CoreServerUUID Points to the Core Server uuid to be used for the create. 


CreateOptions 


FilesetAttrBits 

FilesetAttrs 

ObjectAttrBits 

ObjectAttrs 

DMGFSInfo 


RetFilesetAttrBits 


Specifies what type of fileset to create. There are three options: 
CORENSFILESET - Create the Core Server fileset metadata 

CORE DMG FILESET - Create the DMAP Gateway fileset metadata 

CORE BOTH FILESETS - Create both DMG and Core Server fileset 
metadata 

Specifies which fileset attributes are to be set. 

Points to the fileset attributes to be set. 

Specifies which object attributes are to be set. 

Points to the object attributes to be set. 

DMAP Gateway fileset information. This should be NULL for HPSS-only 
filesets. For linked filesets (archived), this is a pointer to a structure containing 
all the details of the fileset. Refer to the definition of 
dmgfilesetinfot for details (this resides is include/dmg/dmg_types.idl). 
Specifies which fileset attributes were set. 


RetObjectAttrBits 

RetFilesetAttrs 

RetObjectAttrs 

FilesetHandle 


Specifies which object attributes were set. 
Points to the fileset attributes that were set. 
Points to the object attributes that were set. 
Points to the fileset handle created. 
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Return values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned; 
the absolute value of that returned is equal to an ermo value. 

The user is not the root user or a trusted user. 

The CoreServerUUID, FilesetHandle, FilesetAttrs, ObjectAttrs, RetFilesetAttrs 
or the RetObjectAttrs is NULL. 

The file attributes or attributes bits are invalid. 

A file already exist with the specified identifier. 

See Also 

hpss FilesetDelete, hpss FilesetGetAttributes, hpss FilesetSetAttributes. 

Notes 


Error Conditions 

EACCES 

EFAULT 

EINVAL 

EEXIST 


1. If CreateOptions requests a DMG fileset, then DMGFSInfo cannot be NULL. If so, EINVAL will be 
returned. 

2.1.42. hpss_FilesetDelete 

Purpose 

Delete an HPSS fileset. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_FilesetDelete( 
char 

u_signed64 
ns_Obj Handle_t 


*Name, /* IN */ 
*FilesetId, /* IN */ 
*FilesetHandle ); /* IN */ 


Description 

The hpss_FilesetDelete function is called to delete an existing HPSS fileset by either name, id or 
handle. A fileset can be identified by either a name, an ID, or the handle to its root. Only one type 
of identifier can be specified. The other values must be NULL pointers. 

Parameters 

Name Specifies the name of the fileset to be deleted. 

Filesetld Specifies the id of the fileset to be deleted. 

FilesetHandle Specifies the handle of the fileset to be deleted. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned; 
the absolute value of that returned is equal to an ermo value. 

Error Conditions 
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EACCES 

EFAULT 

EINVAL 

ENOENT 


See Also 


The user is not the root user or a trusted user. 

The Name, FilesetID and FilesetHandle arguments are all NULL pointers. 
More that one type of fileset identifier was specified. 

The specified fileset does not exist. 


hpssFilesetCreate, hpss FilesetGetAttributes, hpssFilesetSetAttributes. 

Notes 


None. 


2.1.43. hpss_FilesetGetAttributes 

Purpose 

Get attributes for an HPSS fileset. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_FilesetGetAttributes( 
char 

u_signed64 
ns_Obj Handle_t 
hpss_uuid_t 
ns_FilesetAttrBits_t 
ns FilesetAttrs t 


* FilesetName, 
*F±lesetId, 

* FilesetHandle, 

*CoreServerUUID, 
FilesetAttrBits, 
* FilesetAttrs ); 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 


Description 

The hpss_FilesetGetAttributes function is called to retrieve the attribute for a specified HPSS fileset by 
supplying either a name, id or handle. Only one type of identifier can be specified. The other values must be 
NULL pointers. If NULL is specified for the Core Server UUID, then the local Core Server will be 
contacted; otherwise the specified Core Server will be contacted to retrieve the fileset information. 

Parameters 

FilesetName 
Filesetld 
FilesetHandle 
CoreServerUUID 
FilesetAttrBits 
FilesetAttrs 
Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned; 
the absolute value of that returned is equal to an ermo value. 


Specifies the name of the fileset to retrieve attributes for. 

Specifies the id of the fileset to retrieve attributes for. 

Specifies the handle of the fileset to retrieve attributes for. 

The Core Server to contact managing the fileset information. 

Specifies the fileset attribute bits that specify the fileset attributes to retrieve. 
Points to the returned fileset attributes. 
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Error Conditions 


EACCES 

EFAULT 

EINVAL 


ENOENT 

See Also 


The user is not the root user or a trusted user. 

The Name, FilesetID and FilesetHandle arguments are all NULL pointers. 
More that one type of fileset identifier was specified or invalid file 
set attribute bits were specified. 

The specified fileset does not exist. 


hpss FilesetSetAttributes, hpss FilesetCreate, hpss FilesetDelete. 

Notes 


None. 

2.1.44. hpss_FilesetListAII 

Purpose 

Obtain a list of all the HPSS filesets. 
Synopsis 


OffsetIn, 

Entries, 

*End, 

*OffsetOut, 
*FSentPtr ); 


#include "hpss_api.h" 
int 

hpss_FilesetListAll( 
u_signed64 
unsigned32 
unsigned32 
u_signed64 
hpss_global_fsent_t 


/* IN */ 
/* IN */ 
/* OUT */ 
/* OUT */ 
/* OUT */ 


Description 

The hpss_FilesetListAll routine is called to get the global fileset attributes for all the filesets in the HPSS 
site. 

Parameters 


Offsetln 

Entries 

End 

OffsetOut 

FSentPtr 


The offset of the first fileset entry to be read. This should be set to zero to start 
before the first call, and subsequent entries can be read by providing the value 
returned in OffsetOut. 

The number of the fileset entries referenced by FSentPtr in hpss_global Jsent t 
entries, for which you have to allocate space. 

Pointer to an area to contain an indication of whether the last fileset entry is 
included in the returned list. The value of End specifies if the end of the list 
was encountered before all the entries were accumulated. 

Pointer to an area to contain the offset of the next fileset entry following those 
returned by this call. OffsetOut is the location where the lookup stops when it 
has accumulated the specified number of fileset entries. 

Pointer to area to contain returned fileset entries. 
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Return Values 

Upon successful completion, a nonnegative value indicating the number of fileset entries is returned. 
Otherwise, a negative value is returned, the absolute value of which is equal to an ermo value defined 
below. 

Error Conditions 

EFAULT The End, OffsetOut or FSentPtr parameter is a NULL pointer. 

EINVAL The Entries parameter specifies zero entries to read. 

See Also 

hpssFilesetCreate. 

Notes 


None. 


2.1.45. hpss_FilesetSetAttributes 

Purpose 

Set attributes for an HPSS fileset. 


Synopsis 

#include "hpss_api.h" 
int 

hpss_FilesetSetAttributes( 
char 

u_signed64 

ns_Obj Handle_t 

ns_FilesetAttrBits_t 

ns_FilesetAttrs_t 

ns_FilesetAttrBits_t 

ns FilesetAttrs t 


*Name r 

*FilesetId, 

* FilesetHandle, 
FilesetAttrBitsIn, 

* FilesetAttrsIn, 
FilesetAttrBitsOut, 
*FilesetAttrsOut ) ; 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 


Description 

The hpss_FilesetSetAttributes function is called to set the attribute for a specified Core Server fileset by 
either name, id or handle. Only one type of identifier can be specified. The other values must be NULL 
pointers. 

Parameters 


Name 

Specifies 

Filesetld 

Specifies 

FilesetHandle 

Specifies 

FilesetAttrBits 

Specifies 
to be set. 

FilesetAttrs 

Points to 


the name of the fileset to retrieve attributes for. 

the id of the fileset to retrieve attributes for. 

the handle of the fileset to retrieve attributes for. 

the fileset attribute bits that specify the fileset attribute values that are 

the fileset attribute values to be set. 
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FilesetAttrBitsOut 


Specifies the fileset attribute bits that specify the fileset attribute values that are 
to be returned. 

FilesetAttrsOut Points to the returned fileset attribute values. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned; the 
absolute value of that returned is equal to an ermo value. 

The user is not the root user or a trusted user. 

The Name, FilesetID and FilesetHandle arguments are all NULL pointers. 

More that one type of fileset identifier was specified or invalid file set attributes 
(or attribute bits) were specified. 

The specified fileset does not exist. 

See Also 


Error Conditions 

EACCES 

EFAULT 


EINVAL 

ENOENT 


hpss FilesetGetAttributes, hpssFilesetCreate, hpss FilesetDelete. 

Notes 


A fileset can be identified by either a name, an ID, or the handle to its root. Only one type of identifier is 
valid. If more than one of the fileset identifiers have non-null pointers, then the call will fail with an 
EINVAL. 

2.1.46. hpss_Fopen 

Purpose 

Open an HPSS file stream. 

Synopsis 

#include "hpss_api.h" 

HPSS FILE * 
hpss_Fopen( 

char *path, /* IN */ 

char *mode ); /* IN */ 


Description 

This function will open an HPSS file pointed to by the path parameter, associate a stream with it and return 
a pointer to an HPSSFILE structure. The pointer can be used with any of the HPSS stream functions. 

Parameters 

path Character string specifying the path/name of the HPSS file to be opened. 

mode File mode (r,w,a,r+,w+,a+). 

Return Values 

If the open command is successful, a pointer to the HPSS FILE structure will be returned. Otherwise, a 
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NULL pointer will be returned and the system ermo value will be set to indicate the error. 


Error Conditions 


EFAULT 

EINVAL 

EIO 

ENOENT 

ENOMEM 

EMFILE 


See Also 


Path parameter is NULL. 

Invalid mode parameter. 

Internal error. 

Path parameter points to an empty string. 
Memory allocation failure. 

Too many open files. 


hpss Fclose, hpss Fread, hpss Fwrite, hpss Fseek, hpss Ftell 

Notes 


If the file is open for update, an output operation cannot be directly followed by an input unless an 
intervening file positioning call is made. Also, an input operation cannot be directly followed by an output 
operation unless an intervening file positioning call is made except when the input encounters an EOF. 

Following is a list of valid values for the mode parameter and their effects on the HPSS stream: 

r Open text file for reading. The stream is positioned at the beginning of the file. 

Open for reading and writing. The stream is positioned at the beginning of the 
r file. 

Truncate the file to zero length or create text file for writing. The stream is 
positioned at the beginning of the file. 

w+ Open for reading and writing. The file is created if it doesn't exist, otherwise it 

is truncated to zero length. The stream is positioned at the beginning of the file. 

a Open for appending (writing at end of file). The file is created if it doesn't exist. 

The stream is positioned at the end of the file. 

a+ Open for reading and appending (writing at end of file). The file is created if it 

does not exist. The initial file position for reading is at the beginning of the file, 
but output is always appended to the end of the file. 


2.1.47. hpss_Fpreallocate 

Purpose 

Set the length of a file and preallocate storage segments. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Fpreallocate( 

int Fildes, /* IN */ 

u_signed64 Length ); /* IN */ 
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Description 


The hpss_Fpreallocate routine sets the length of an open file, specified by the Fildes argument. The 
Length parameter specifies the requested length. It must be greater than the current size of the file. 
Additional storage space is preallocated for the file and a hole is created in the file from the current size to 
the requested length. 

Parameters 

Fildes Specifies file descriptor identifying file to be queried. 

Length Specifies the desired length of the file. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EBADF The specified file descriptor does not correspond to a file opened for writing. 

EBUSY The specified file descriptor is currently in use. 

ENOSPC The requested storage resources could not be allocated. 

EINVAL There is not a disk storage class at the top of the storage hierarchy. 

See Also 


hpss Ftruncate, hpss Truncate, hpss Fclear, hpss FileSetAttributes. 

Notes 


There must be a disk storage class at the top of the storage hierarchy in which the file resides. 

2.1.48. hpss_Fread 

Purpose 

Read from an HPSS Stream. 

Synopsis 

#include "hpss_api.h" 
size_t 
hpss_Fread( 

void *Ptr 

size_t Size, 

size_t Num, 

HPSS_FILE *hpss_Stream) 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 


Description 

The hpss_Fread function will provide a buffered EO front-end to the hpssRead function. It will support 
both 32-bit and 64-bit size t values depending on how the library is built. 

The function will copy the number of data items specified by the 'Num' parameter into an array pointed to 
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by the 'Ptr' parameter from the input stream hpssStream. Each data item consists of the number of bytes 
specified by the 'Size' parameter. 

The function will stop copying bytes if an end-of-file (EOF) or error condition is encountered while reading 
from the input specified by the 'hpss Stream' parameter, or the number of data items specified by the 'Num' 
parameter have been copied. 

Parameters 

Ptr Pointer to an array of data items of size 'Size' bytes. 

Size Specifies the size in bytes of each data item in the 'Ptr' array. 

Num Number of data items in the 'Ptr' array. 

hpss Stream The open HPSS Stream pointer. 

Return Values 
Return Values 

On successful completion, the number of data items read will be returned. The global ermo value will be 
set to a non-zero value if an error condition occurs. 

Error Conditions 


EBADF 

EINVAL 

EFAULT 

EBUSY 

ESTA TE 

EPERM 


See Also 


Invalid file descriptor or file not open. 

Invalid input parameter (Ptr Null or Size zero) 

NULL stream pointer. 

HPSS file table entry busy. 

Stale Connection. 

File opened for write only or trying to read after a write without a file 
positioning operation. 


hpss Fseek, hpss_Fflush,hpss_Fwrite, hpss Fopen, hpss Fclose, hpss Ftell 


The behavior of this function is modeled after the system fread() routine. 

2.1.49. hpss_Fseek 

Purpose 

Seek on an HPSS Stream. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Fseek( 

HPSS_FILE *hpss_Stream 
ssize_t Offsetln, 

int Whence ); 


/* IN */ 
/* IN */ 
/* IN */ 
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Description 

The hpss_Fseek routine sets the file position of an opened HPSS file. 

Parameters 

hpss Stream The open HPSS Stream pointer. 

Ojfsetln The number of bytes to adjust the HPSS file position. Can be negative or 

positive, or zero. 

Whence Origin for the seek. 

SEEK SET File position set to Offsetln from beginning of file. 

SEEK CUR File position adjusted by Offsetln from current file position. 

SEEK END File position set to fde size + Offsetln. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EBADF Invalid file descriptor or file not open. 

EINVAL Invalid input parameter. 

EFAULT Invalid or NULL pointer. 

EBUSY HPSS fde table entry busy. 

ESTALE Stale Connection. 

EPERM File opened for write only or trying to read after a write without a file 

positioning operation. 

See Also 

hpss Lseek, hpss Fflush 

Notes 

The behavior of this function is modeled after the system fseekO routine. 

2.1.50. hpss_Fstat 

Purpose 

Get fde status (POSIX). 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Fstat( 

int Fildes, /* IN */ 

hpss_stat_t *Buf ) ; /* OUT */ 
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Description 


The hpss_Fstat function obtains information about the open file identified by Fildes and returns it in the 
structure pointed to by Buf. Refer to POSIX. 1 for more detailed information. 

Parameters 

Fildes Specifies the file descriptor identifying the file to be queried. 

Buf Points to a stat structure that will contain the information for the file. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX. 1 stat. 

Error Conditions 

EBADF The file descriptor supplied does not correspond to an open file. 

EBUSY Another thread is currently manipulating this entry. 

EFAULT The Buf parameter is a NULL pointer. 

See Also 

hpss Chown, hpss Chmod, hpss Utime, hpss FileGetAttributes, hpssFileSetAttributes, hpss Stat, 
hpss Lstat, hpss GetListAttrs, hpss ReadAttrs. 

Notes 


None. 

2.1.51. hpss_Fsync 

Purpose 

This function is currently a no-op and will return a zero value as long as hpssfd is a valid FIPSS file 
descriptor. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Fsync( 

int hpss_fd) ; /* IN */ 

Description 

The hpss_Fsync routine returns a zero as long as the hpss fd is valid. 

Parameters 

hpss Jd HPSS file descriptor. 

Return Values 

If the input value for hpss fd is valid, zero is returned. Otherwise, a negative value is returned, the absolute 
value of which is equal to an ermo value defined below. 
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Error Conditions 


EBADF Invalid file descriptor. 

See Also 

None 

Notes 

None 

2.1.52. hpss_Ftell 

Purpose 

Get the current file position of an HPSS file stream. 

Synopsis 

#include "hpss_api.h" 
long 

hpss_Ftell( 

HPSS_FILE *hpss_Stream) ; /* IN */ 

Description 

The hpss_Ftell routine returns the file position indicator of the open HPSS file. 

Parameters 

hpssStream HPSS stream pointer. 

Return Values 

On successful completion the value of the current file position is returned. Otherwise, a negative value is 
returned, the absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EBADF 
EFAULT 

See Also 

None 

Notes 

None 

2.1.53. hpss_Ftruncate 

Purpose 

Set the length of an HPSS file stream. 

Synopsis 


Invalid file descriptor. 
NULL input pointer. 
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#include "hpss_api.h" 
hpss_Ftruncate( 

int Fildes, /* IN */ 

u_signed64 Length ); /* IN */ 


Description 

The hpss_Ftruncate routine sets the length of an open file, specified by the Fildes argument. If the new 
file length is less than the current length, the space allocated beyond the new length will be freed. If the 
new length is greater than the current length, a hole is created in the file. 

Parameters 

Fildes Specifies the file descriptor identifying the open file for which the length is to 

be set. 

Length Specifies the new length of the file. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EBADF The specified file descriptor does not correspond to a file opened for writing. 

EBUSY The specified file descriptor is currently in use. 

EINVAL No DMAP support compiled in. 


See Also 


hpss Truncate, hpss Fclear, hpssFileSetAttributes. 

Notes 


2.1.54. hpss_Fwrite 

Purpose 

Write to an HPSS file stream. 

Synopsis 

#include "hpss_api.h" 

size_t 

hpss_Fwrite( 

void *Ptr, 

size_t Size, 

size_t Num, 

HPSS_FILE *hpss_Stream ); 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 


Description 

The hpss_Fwrite function will provide a buffered I/O front-end to the hpss_Write function. It will 
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support both 32-bit and 64-bit sizet values depending on how the library is built. 

The function will write the number of data items specified by the 'Num' parameter from an array pointed to 
by the 'Ptr' parameter to the input stream hpssStream. Each data item consists of the number of 
bytes secified by the 'Size' parameter. 

The function will stop writing bytes if an error condition is encountered or the number of data items 
specified by the 'Num' parameter have been written. 

Parameters 

Ptr Pointer to an array of data items of size 'Size 1 bytes. 

Size Specifies the size in bytes of each data item in the Ptr' array. 

Num Number of data items in the 'Ptr' array. 

hpss Stream HPSS stream pointer. 

Return Values 

On successful completion, the number of data items written will be returned. The global ermo value will be 
set to a non-zero value if an error condition occurs. 

Error Conditions 


EBADF 

EFAULT 

EFBIG 

EBUSY 

ENOENT 

ENOMEM 

EINVAL 

See Also 


Invalid HPSS file descriptor. 

NULL pointer. 

Size of write request greater than 2GB. 
Another thread is accessing the file table entry. 
File doesn't exist. 

Memory allocation failure. 

Invalid input parameter. 


hpss Fread, hpss Fopen, hpss Fclose, hpssFsync, hpssFcntl, hpss Ftell, hpss Fflush 

Notes 

None 


2.1.55. hpss_GetAcct 

Purpose 

Query the default and current account codes. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_GetAcct( 

acct_rec_t *RetDefAcct, /* OUT */ 

acct_rec_t *RetCurAcct ); /* OUT */ 
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Description 


The hpss_GetAcct routine returns the default and current account codes for the calling thread. 

Parameters 

RetDefAcct Points to an area that will contain the default account code. 

RetCurAcct Points to an area that will contain the current account code. 

Return Values 

Upon successful completion, hpss_GetAcct returns zero. Otherwise, hpss_GetAcct returns a negative 
value; the absolute value of which indicates the specific error. 

Error Conditions 

EFAULT The RetDefAcct or RetCurAcct parameter is a NULL pointer. 

See Also 

hpss AcctCodeToName, hpss AcctNameToCode , hpss Chacct, hpss ChacctByName, 
hpssGetAcctName, hpss SetAcct, hpssSetAcctByName 

Notes 


None. 

2.1.56. hpss_GetAcctName 

Purpose 

Retrieve the current account name. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_GetAcctName( 

char *AcctName ) /* OUT */ 


Description 

The hpss GetAcctName routine retrieves the name of the current session account for this thread. Since 
each site contacted by each thread in the Client API can have its own session account name, the account 
name for the site managing the current working directory is returned. 

Parameters 

AcctName The name of the thread's current session account. Account name should be a 

string of at least HPSS_MAX_ACCOUNT_NAME (128) characters. 


Return Values 

Upon successful completion, hpss GetAcctName returns 0. Otherwise, hpss GetAcctName returns a nega¬ 
tive value, the absolute value of which indicates the specific error. 

Error Conditions 
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EFAULT 


A NULL AcctName was provided. 


See Also 


hpssGetAcct, hpssChacct, hpssSetAcct, hpssSetAcctByName, hpssChacctByName. 

Notes 


None. 


2.1.57. hpss_GetACL 

Purpose 

Query the Access Control List of a file. 

Synopsis 

#include "hpss_api.h" 
int 

hpss GetACL( 

IN */ 
IN */ 
OUT */ 


char *Path, /* 
unsigned32 Options, /* 
ns_ACLConfArray_t **ACL ); /* 


Description 

The hpss_GetACL function returns the access control list information for the named file. 

Parameters 


Path Names the file for which the ACL is being queried. 

Options Bit vector used to specify what type of ACL is to be retrieved. One of: 

HPSS ACL OPTION OBJ - return object's normal ACL. 

HPSS ACL OPTION IO - return the initial-object ACL. (only valid for 
directory objects) 

HPSS ACL OPTION IC - return the initial-container ACL. (only valid for 
directory objects) 

ACL Points to the beginning of the returned list of ACL entries. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below: 

Search permission is denied for a component of the path prefix. 

The Path or ACL parameter is a NULL pointer. 

Exactly one of the HPSS ACL OPTION * bits must be set in the Options bit 
vector to avoid receiving this error. 


Error Conditions 

EACCES 

EFAULT 

EINVAL 
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ENAMETOOLONG 


ENOENT 

ENOTDIR 

EPERM 


See Also 


The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

The named file does not exist, or the Path argument points to an empty string. 
A component of the Path prefix is not a directory. 

The client does not have the appropriate privileges to perform the operation. 


hpssGetACLHandle, hpssSetACL, hpssSetACLHandle, hpssDeleteACL, 
hpssDeleteACLHandle, hpssUpdateACL, hpssUpdateACLHandle. 


The user is responsible for freeing the ACL return parameter. 


2.1.58. hpss_GetACLHandle 

Purpose 

Query the Access Control List of a file. 


Synopsis 


#include "hpss_api.h" 
int 

hpss_GetACLHandle( 

ns_ObjHandle_t *ObjHandle, /* 

char *Path, /* 

sec_cred_t *Ucred, /* 

unsigned32 Options, /* 

ns_ACLConfArray_t **ACL ); /* 


IN */ 
IN */ 
IN */ 
IN */ 
OUT */ 


Description 

The hpss_GetACLHandle function returns the access control list information for the named file taken 
relative to the directory indicated by ObjHandle. 

Parameters 

ns ObjHandle_t Parent object handle. 

Path Names the file for which the ACL is being queried. 

Ucred User credentials. 

Options Bit vector used to specify what type of ACL is to be retrieved. One of: 

HPSS ACL OPTION OBJ - return object's normal ACL. 

HPSS ACL OPTION IO - return the initial-object ACL. (only valid for 
directory objects) 

HPSS ACL OPTION_IC - return the initial-container ACL. (only valid for 
directory objects) 

ACL Points to the beginning of the returned list of ACL entries. 

Return Values 
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Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below: 

Search permission is denied on a component of the path prefix. 

The Path or ACL parameter is a NULL pointer. 

Exactly one of the HPSS ACL OPTION * bits must be set in the Options bit 
vector to avoid receiving this error, or ObjHandle is NULL. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 

EPERM The client does not have the appropriate privileges to perform the operation. 

See Also 

hpssSetACL, hpssGetACL, hpssDeleteACL, hpssDeleteACLHandle, hpssUpdateACL, 
hpssUpdateACLHandle. 

Notes 


Error Conditions 


EACCES 

EFAULT 


1. The user is responsible for freeing the ACL return parameter. 

2. If the Ucred parameter is NULL, the credentials in the current thread context are used. 

2.1.59. hpss_GetAsynchStatus 

Purpose 

Get status associated with a background request where callback information was previously provided. 

Synopsis 

#include "hpss_api.h" 

int 

hpss_GetAsynchStatus( 

signed32 CallBackld, /*IN*/ 

hpssoid_t *BfId, /*IN*/ 

signed32 *Status ); /*OUT*/ 


Description 

The hpss_GetAsynchStatus routine queries the Root Core Server to obtain status information for the 
specified background request. 

Parameters 

CallBackld Identifies the background request. 

Bfld Bitfile identifier returned from the stage callback request. 

Status Returned stage status. This can be one of the following: 

HPSS STAGE STATUS UNKNOWN - no status available. 
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HPSSSTAGESTATUSQUEUED - request still in queue and not yet active. 
HPSS STAGE STATUS ACTIVE - stage active and in progress. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EINVAL The Bfld parameter is not a valid pointer. 

EFAULT The Status parameter is a NULL pointer. 

See Also 


hpssStageCallBack, hpssStage. 


Notes 


2.1.60. hpss_GetAttrHandle 

Purpose 

Get attributes for a file. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_GetAttrHandle( 
ns_Obj Handle_t 
char 

sec_cred_t 
ns_Obj Handle_t 
hps s_au thz_token_t 
hps s_vattr_t 


*ObjHandle, 
*Path, 

*Ucred, 
*HandleOut, 
*AuthzTicket, 
*AttrOut) ; 


/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 
/* OUT */ 
/* OUT */ 


Description 

The hpss GetAttrHandle function obtains information about the file or directory named by 'Path', taken 
relative to the directory indicated by ObjHandle. Attributes are returned in the area pointed to by AttrOut. 
If Path refers to a symbolic link, information will be returned about the link itself. 

Parameters 


ns ObjHandleJ 

Path 

Ucred 

HandleOut 

AttrOut 


Parent object handle. 

Points to the path name of the file being queried. 

User credentials. If NULL, the credentials in the current thread context will be 
used. 

Returned object handle. 

Points to the structure that will hold the file attributes. 
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Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which indicates the specific error. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix. 

EFAULT The Path or AttrOut parameter is a NULL pointer. 

EINVAL The ObjHandle parameter is NULL. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 


hpssFileGetAttributesHandle, hpssFileGetXAttributes, 

hpss_GetRawAttrHandle,hpss_FileGetAttributesSOID, hpssFileSetAttributes, hpssStat, 
hpssFstat, hpssLstat, hpssGetListAttrs, hpssReadAttrs. 


2.1.61. hpss_GetAuthType 

Purpose 

Get current default authenticator type for the specified authentication mechanism. 

Synopsis 

#include "hpss_api.h" 
signed32 

hpss_GetAuthType( 

hpss_authn_mech_t AuthMech, /* IN */ 

hpss_rpc_auth_type_t *AuthType) ; /* OUT */ 


Description 

The hpss_GetAuthType is called to get the current (or default) authenticator type for the specified 
authentication mechanism. 

Parameter 


AuthMech Authentication mechanism being used. Valid values are: 

hpss_authn_mech_krb5 (Kerberos 5) 
hpssauthnmechunix (Unix) 

AuthType Authenticator type. Valid values are: 

hpss_rpc_auth_type_keytab (Kerberos 5) 
hpss_rpc_auth_type_keyfile (Unix) 
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Return Values 

Upon successful completion, a valid authenticator type is returned. If the authtype cannot be determined, 
HPSS_ENOTSUPPORTED is returned. 

Error Conditions 

ENOTSUPPORTED Authentication mechanism is not supported. 

See Also 

None. 

Notes 

None. 

2.1.62. hpss_GetConfiguration 

Purpose 

Query the current Client API configuration information. 

Synopsis 

#include "hpss_api.h" 
long 

hpss_GetConfiguration( 

api_config_t *ConfigOut ) ; /* OUT */ 

Description 

The hpss_GetConfiguration routine returns the current configuration values for the Client API. 

Parameters 

ConfigOut Points to an area that will contain the current configuration attribute value 

settings. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EFAULT The ConfigOut parameter is a NULL pointer. 

See Also 

hpssSetConliguration. 

Notes 

None. 

2.1.63. hpss_Getcwd 

Purpose 
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Get current working directory. 


Synopsis 

#include "hpss_api.h" 
int 

hpss_Getcwd( 

char *Buf, /* OUT */ 

size_t Size ); /* IN */ 


Description 

The hpss_Getcwd function copies an absolute path name of the current working directory to the character 
array pointed to by Buf The Size argument is the size in bytes of the array pointed to by Buf. 

Parameters 

Buf Points to an array to contain the current working directory path name. 

Size Specifies the size, in bytes, of the array pointed to by Buf. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX. 1 getcwd. 

Error Conditions 

EACCES Read or Search permission is denied on a component of the path name. 

EFAULT The Buf parameter is a NULL pointer. 

EINVAL The Size argument is zero. 

ERANGE The Size argument is greater than zero, but smaller than the length of the path 

name plus 1. 

See Also 

hpss Chdir, hpss Chroot. 

Notes 


hpss_Getcwd is altered from POSIX. 1 getcwd in that it returns an integer value to be more consistent with 
other HPSS calls. 

2.1.64. hpss_GetDistFile 

Purpose 

Get a distributed file's information. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_GetDistFile( 

int Fildes, /* IN */ 

api_dist_file_info_t *FileInfo) ; /* OUT */ 


HPSS Programmer's Reference 
Release 6.2 (Revision 2.0) 


July 2008 


90 



Description 

The hpss GetDistFile function extracts a file table entry for a supplied open file descriptor. The function 
returns a pointer to the file table information. 

Parameters 

FileDes Open file descriptor. 

Filelnfo Pointer to returned file information. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value. 

Error Conditions 

EBADF Invalid file descriptor Fildes. 

EBUSY Another thread is currently manipulating this entry. 

EFAULT Filelnfo is a NULL pointer. 

See Also 

hpssInsertDistFile 

Notes 


None. 


2.1.65. hpss_GetJunctions 

Purpose 

Get a list of all junctions residing in a given storage subsystem’s name space. 


Synopsis 

#include "hpss_api.h" 
int 

hpss_GetJunctions( 
unsigned32 
u_signed64 
unsigned32 
unsigned32 
u_signed64 
hpss_junction_ent_t 


SubsystemID, 
Offsetln, 
Entries, 
*End, 

*OffsetOut, 
*JentPtr ); 


/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 
/* OUT */ 
/* OUT */ 


Description 

The hpss_GetJunctions routine is called to get an array of junctions residing in the specified storage 
subsystem. 

Parameters 

SubsystemID ID of the storage subsystem where the junction resides. 
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Offsetln 


Entries 


End 


OffsetOut 


JentPtr 

Return Values 


The offset of the first junction entry to be read. This should be set to zero to 
start before the first call, and subsequent entries can be read by providing the 
value returned in OffsetOut. 

The number of the junction entires referenced by JentPtr in 
hpss junction ent t entries, for which you have to allocate space. 

Pointer to an area to contain an indication of whether the last junction entry is 
included in the returned list. The value of End specifies if the end of the list 
was encountered before all the entries were accumulated. 

Pointer to an area to contain the offset of the next junction entry following 
those returned by this call. OffsetOut is the location where the lookup stops 
when it has accumulated the specified number of junction entries. 

Pointer to an area to contain the returned junction entries. 


Upon successful completion, a nonnegative value indicating the number of junction entries read is returned. 
Otherwise, a negative value is returned, the absolute value of which is equal to an ermo value defined 
below. 


Error Conditions 


EFAULT The End, OffsetOut or JentPtr parameter is a NULL pointer. 

EINVAL The Entries parameter specifies zero entries to read. 


See Also 


hpss FilesetCreate, hpssJunctionCreate, hpss JunctionCreateHandle, hpss JunctionDelete, 
hpssJunctionDeleteHandle. 


None. 

2.1.66. hpss_GetListAttrs 

Purpose 

Get attributes for a file, suitable for a directory listing. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_GetListAttrs( 

char *Path, /* IN */ 

hpss_Attrs_t *AttrOut ) ; /* OUT */ 

Description 

The hpss_GetListAttrs function returns the attributes associated with the file named by Path. The 
attributes include information suitable for a long directory listing, including 64-bit file length and Class of 
Service. If Path refers to a junction, the junction will be traversed. If Path refers to a symbolic link, 
information will be returned about the link itself. 
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Parameters 


Path Points to the path name of the file being queried. 

AttrOut Points to a structure that will contain the attribute information for the file; not to 

be confused with the stat structure returned by hpss_Stat or hpss_Fstat. 

Return Values 

Upon successful completion, a value of zero is returned . Otherwise, a negative value is returned, the 
absolute value of which indicates the specific error. 

Error Conditions 

EACCES Search permission is denied for a component of the path prefix. 

EFAULT The Path or AttrOut parameter is a NULL pointer. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 


hpss Chown, hpss Chmod, hpssUtime, hpssFileGetAttributes, hpssFileGetAttributesHandle, 
hpssFileGetAttributesSOID, hpssFileSetAttributes, hpssFileSetAttributesHandle, 
hpssFileSetAttributesSOID, hpss Stat, hpss Fstat, hpssReadAttrs, hpssGetJunctionAttrs. 


None. 

2.1.67. hpss_GetJunctionAttrs 

Purpose 

Get attributes for a file or junction. It does not traverse a junction or symbolic link. 
Synopsis 

#include "hpss_api.h" 
int 

hpss_GetJunctionAttrs( 

char *Path, /* IN */ 

hpss_Attrs_t *AttrOut ) ; /* OUT */ 


Description 

The hpss_GetJunctionAttrs function returns the attributes associated with the file named by Path. The 
attributes include information suitable for a long directory listing, including 64-bit file length and Class of 
Service. If Path refers to a junction or symbolic link, information will be returned about the junction or link 
itself. 

Parameters 

Path Points to the path name of the file being queried. 
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AttrOut 


Points to a structure that will contain the attribute information for the file; not to 
be confused with the stat structure returned by hpss_Stat or hpss_Fstat. 


Return Values 

Upon successful completion, a value of zero is returned . Otherwise, a negative value is returned, the 
absolute value of which indicates the specific error. 

Error Conditions 


EACCES 

EFAULT 

ENAMETOOLONG 


ENOENT 

ENOTDIR 


See Also 


Search permission is denied for a component of the path prefix. 

The Path or AttrOut parameter is a NULL pointer. 

The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

The named file does not exist, or the Path argument points to an empty string. 
A component of the Path prefix is not a directory. 


hpss Chown, hpss Chmod, hpssUtime, hpssFileGetAttributes, hpssFileGetAttributesHandle, 
hpssFileGetAttributesSOID, hpssFileSetAttributes, hpssFileSetAttributesHandle, 
hpssFileSetAttributesSOID, hpss Stat, hpss Fstat, hpssReadAttrs, hpssGetListAttrs. 


Notes 


None. 

2.1.68. hpss_GetObjld 

Purpose 

Get HPSS Object ID given an object handle. 

Synopsis 

#include "hpss_api.h" 
unsigned32 
hpss_GetObjId( 

ns_ObjHandle_t *ObjHandle); /* IN */ 


Description 

This routine returns the object id given the object handle. 

Parameters 

ObjHandle HPSS object handle. 

Return Values 

Upon successful completion, the object id is returned. Otherwise, a negative value is returned, the absolute 
value of which is equal to an ermo value defined below. 

Error Conditions 
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EFAULT The ObjHandle parameter is a NULL pointer. 

See Also 

hpssGetObjType 

Notes 

None. 

2.1.69. hpss_GetObjType 

Purpose 

Get HPSS Object type given an object handle. 

Synopsis 

#include "hpss_api.h" 
unsigned32 
hpss_GetObjType( 

ns_ObjHandle_t *ObjHandle); /* IN */ 

Description 

This routine returns the object type given the object handle. 

Parameters 

ObjHandle HPSS object handle. 

Return Values 

Upon successful completion, the object type is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. Valid return types are: 

NSOBJECTTYPEDIRECTORY 
N SOB JECTTYPEJUNCTION 
N SOB JECTTYPEFILE 
N SOB JECTTYPEHARDLINK 
N SOB JECTTYPES YMLINK 
Error Conditions 

EFAULT The ObjHandle parameter is a NULL pointer. 

EINVAL The ObjHandle points to an invalid object. 

See Also 

hpssGetObjld 

Notes 

None. 
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2.1.70. hpss_GetPathHandle 

Purpose 

Get HPSS pathname and root fileset handle. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_GetPathHandle( 

ns_ObjHandle_t *ObjHandle); /* IN */ 

ns_ObjHandle_t *FilesetRootHandle, /* OUT */ 

char *Path); /* OUT */ 

Description 

The hpss_GetPathHandle function outputs a pathname and a root fileset handle that corresponds to an 
object handle.. 

Parameters 

ObjHandle HPSS object handle. 

FilesetRootHandle Fileset root handle. 

Path Path to object identified by ObjHandle parameter. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EFAULT 
EINVAL 

See Also 

None. 

Notes 

None. 

2.1.71. hpss_GetRawAttrHandle 

Purpose 

Get attributes for a file. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_GetRawAttrHandle( 

ns_ObjHandle_t *ObjHandle, /* IN */ 


The Path or FilesetRootHandle parameter is NULL. 
The ObjHandle is NULL. 
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char 

sec_cred_t 
ns_Obj Handle_t 
hps s_authz_token_t 
hps s_vattr_t 


*Path, 

*Ucred, 

*HandleOut, 

* AuthzTicket, 
*AttrOut ); 


/* IN */ 
/* IN */ 
/* OUT */ 
/* OUT */ 
/* OUT */ 


Description 

The hpss_GetRawAttrHandle function obtains information about the symlink or the junction named by 
Path, taken relative to the directory indicated by ObjHandle. Attributes are returned in the area pointed to 
by AttrOut. 

Parameters 


nsObjHandlet 

Path 

Ucred 

HandleOut 

AuthzTicket 

AttrOut 

Return Values 


Parent object handle. 

Points to the path name of the file being queried. 

User credentials. If NULL, the credentials in the current thread context will be 
used. 

Returned object handle. 

Returned authorization ticket. 

Points to the structure that will hold the file attributes. 


Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which indicates the specific error. 


Error Conditions 


EACCES 

EFAULT 

EINVAL 

ENAMETOOLONG 

ENOENT 

ENOTDIR 


Search permission is denied for a component of the path prefix. 

The Path or AttrOut parameter is a NULL pointer. 

The ObjHandle parameter is NULL. 

The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

The named file does not exist, or the Path argument points to an empty string. 
A component of the Path prefix is not a directory. 


See Also 


hpss FileGetAttributesHandle, hpss FileGetXAttributes, 

hpss_GetRawAttrHandle,hpss_FileGetAttributesSOID, hpss FileSetAttributes, hpss Stat, 
hpss Fstat, hpss Lstat, hpss GetListAttrs, hpss ReadAttrs. 


None. 

2.1.72. hpss_GetSubSysStats 

Purpose 
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Query Storage Subsystem statistics. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_GetSubSysStats( 

unsigned32 SubsystemlD, /* IN */ 

subsys_stats_t *StatsOut ) ; /* OUT */ 


Description 

The hpss_GetSubSysStats routine returns the stage, migration, purge, and delete counts for a subsystem 
along with the time these counts were last reset. 

Parameters 

SubsystemlD Subsystem identifier. 

StatsOut Points to an area that will contain the current statistics values. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EFAULT The StatsOut parameter is a NULL pointer. 


See Also 


hpssResetSubSysStats. 


Notes 


None. 

2.1.73. hpss_GetThreadUcred 

Purpose 

Gets the user credentials for the currently running thread. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_GetThreadUcred( 

sec_Cred_t *RetUcred ) ; /* OUT */ 


Description 

The hpss_GetThreadUcred function is used to get the user credentials for the currently running thread. 

Parameters 

RetUcred On success, this points to the current client credentials. 
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Return Values 

Upon successful completion, a value of zero is returned . Otherwise, a negative value is returned, the 
absolute value of which indicates the specific error. 

Error Conditions 

EFAULT RetUcred is a NULL pointer. 


See Also 


None. 


Notes 


2.1.74. hpss_HandleCompare 

Purpose 

Compares two object handles. 

Synopsis 

#include "hpss_api.h" 
unsigned32 
hpss_HandleCompare( 

ns_ObjHandle_t *FirstObjHandle, /* IN */ 

ns_ObjHandle_t *SecondObjHandle); /* IN */ 


Description 

This function compares some fields in two object handles to determine if the handles map to the same 
object. True (1) is returned if the handles are for the same object and false (0) is returned if they are not for 
the same object. 

Parameters 

FirstObjHandle Handle to the first object for comparison. 

FirstObjHandle Handle to the second object for comparison. 

Return Values 

Upon successful completion, a value of zero (false) or one (true) is returned . Otherwise, a negative value is 
returned, the absolute value of which indicates the specific error. 

Error Conditions 
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EINVAL 


One or both object handles point to an invalid object type or are NULL pointers. 
Valid object types are: 

NSOBJECTTYPEDIRECTORY 

NSOBJECTTYPEJUNCTION 
N SOB JECTTYPEFILE 
N SOBJECTTYPEHARDLINK 
N SOB JECTTYPES YMLINK 

See Also 

hpssGetObjType, hpssGetObjld 

Notes 

None. 

2.1.75. hpssJnsertDistFile 

Purpose 

Insert a distributed file given the file's information. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_InsertDistFile( 

api_dist_file_info_t *F±leInfo) ; /* IN */ 

Description 

The hpss_InsertDistFile function attempts to insert an extracted file table entry into the current file table. 

Parameters 

Filelnfo Pointer to file table information. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value. 

Error Conditions 

EFAULT Filelnfo is a NULL pointer. 

EINVAL Checksum on file information failed. 

EMFILE Too many open file descriptors. 

See Also 

hpssGetDistFile 

Notes 
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1. A file entry can only be inserted if it had previously been extracted using hpss_GetDistFile. 

2. The process will be killed if the file descriptor table is inconsistent. 

2.1.76. hpss_JunctionCreate 

Purpose 

Create a junction to an HPSS fileset or directory. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_JunctionCreate( 

char *Path, /* IN */ 

ns_ObjHandle_t * SourceHandle, /* IN */ 

ns_ObjHandle_t * JunctionHandle ); /* OUT */ 


Description 

The hpss_JunctionCreate function is called to create a HPSS junction to the specified directory or fileset 
handle. 

Parameters 

Path Specifies path name of the new junction. 

SourceHandle Points to the directory or fileset handle that is used for the source of the new 

junction. 

JunctionHandle Specifies the returned handle for the newly created junction. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value. 

Error Conditions 

EFAULT Either the Path, SourceHandle, or JunctionHandle parameter is a NULL pointer. 

ENAMETOOLONG The length of the Path argument exceeds the system imposed limit, or a 

component of the pathname exceeds the system imposed limit. 

ENOENT The Path argument points to an empty string. 

EEXIST The named path already exists in the HPSS name space. 

EACCES The requesting client is not the root user or a trusted user with write permissions. 

EINVAL The SourceHandle parameter doesn’t point to a directory handle. 

See Also 

hpssFilesetCreate, hpssGetJunctions, hpssJunctionCreateHandle, hpssJunctionDelete, 
hpssJunctionDeleteHandle. 

Notes 
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None. 


2.1.77. hpss_JunctionCreateHandle 

Purpose 

Create a junction to an HPSS fileset or directory. 
Synopsis 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 


#include "hpss_ap 
int 

hpss_JunctionCreateHandle( 


ns_Obj Handle_ 
char 

ns_Obj Handle_t 
sec_cred_t 
ns_Obj Handle_t 


*ParentHandle, 
*Path, 

* SourceHandle, 
*Ucred, 

* JunctionHandle ) ; 


Description 

The hpss_JunctionCreateHandle function is called to create a HPSS junction to the specified directory or 
fileset handle. 

Parameters 


ParentHandle 

Path 

SourceHandle 

Ucred 

unctionHandle 


Specifies the directory for the new junction. 

Specifies path name of the new junction. 

Points to the directory or fileset handle that is used for the source of the new 
junction. 

User credentials. 

Specifies the returned handle for the newly created junction. 


Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value. 

Error Conditions 


EFAULT Either the Path, SourceHandle, or JunctionHandle parameter is a NULL pointer. 

ENAMETOOLONG The length of the Path argument exceeds the system imposed limit, or a 

component of the pathname exceeds the system imposed limit. 

ENOENT The Path argument points to an empty string. 

EEXIST The named path already exists in the HPSS name space. 

EACCES The requesting client is not the root user or a trusted user with write permissions. 

EINVAL The SourceHandle parameter doesn’t point to a directory handle or the Path is 

invalid. 


See Also 
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hpssFilesetCreate, hpssGetJunctions, hpssJunctionCreate, hpssJunctionDelete, 
hpssJunctionDeleteHandle. 

Notes 

None. 

2.1.78. hpss_JunctionDelete 

Purpose 

Delete a junction. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_JunctionDelete( 

char *Path ); /* IN */ 

Description 

The hpss_JunctionDelete is called to delete the junction specified by the Path input parameter. 

Parameters 

Path Specifies the name of the junction to be deleted. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value. 

Error Conditions 

ENOENT The Path parameter is an empty string or doesn’t refer to an existing object 

EFAULT The Path parameter is NULL. 

EINVAL The Path parameter doesn’t refer to a junction. 

EACCES The requesting client is not the root user or a trusted user with write permissions. 

See Also 

hpss JunctionCreate, hpssJunctionCreateHandle, hpss JunctionDeleteHandle. 

Notes 

None. 

2.1.79. hpssJunctionDeleteHandle 

Purpose 

Delete a junction. 

Synopsis 

#include "hpss_api.h" 
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hpss_JunctionDeleteHandle( 

ns_ObjHandle_t *ParentHandle, /* IN */ 

char *Path, /* IN */ 

sec_cred_t *Ucred) ; /* IN */ 

Description 

The hpss_JunctionDeleteHandle is called to delete the junction specified by the ParentHandle and Path 
input parameters. 

Parameters 

ParentHandh 
Path 
Ucred 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value. 

Error Conditions 

ENOENT The Path parameter is an empty string or doesn’t refer to an existing object 

EFAULT The Path parameter is NULL. 

EINVAL The Path parameter doesn’t refer to a junction or the ParentHandle is NULL. 

EACCES The requesting client is not the root user or a trusted user with write permissions. 

See Also 

hpss JunctionCreate, hpss JunctionCreateHandle, hpss JunctionDelete. 

Notes 

If Ucred is NULL, the credentials in the current thread context are used. 

2.1.80. hpssJJnk 

Purpose 

Create a hard link to an existing HPSS file. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Link( 

char *Existing, /* IN */ 
char *New ); /* IN */ 

Description 

The hpss_Link routine creates a hard link to an existing file (hard links to directories are not currently 


Parent directory. 

Specifies the name of the junction to be deleted. 
User credentials. 
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supported), given the path name of the existing file, Existing, and the path name of the new link, New. 

Parameters 

Existing Specifies the path name of the existing file to which the link is to be created. 

New Specifies the path name of the new link. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix, or write 

permission is denied on the parent directory of the new link. 

EEXIST The object identified by New already exists. 

EFAULT The Existing or New parameter is a NULL pointer. 

EPERM The object specified by Existing is a directory. 

EMLINK The object specified by Existing is a directory. 

ENAMETOOLONG The length of the Existing or New argument exceeds the system-imposed path 
name limit or a path name component exceeds the system-imposed limit. 

ENOENT No entry exists for the specified file. 

ENOTDIR A component of the path prefix is not a directory. 

See Also 

hpssLinkHandle, hpssSymlink, hpssUnlink, hpssUnlinkHandle. 

Notes 


None. 

2.1.81. hpssJJnkHandle 

Purpose 

Create a hard link to an existing HPSS file. 

Synopsis 

/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 


#include "hpss_api.h" 
int 

hpss_LinkHandle( 

ns_Obj Handle_t 
ns_Obj Handle_t 
char 

sec cred t 


*ObjHandle, 
*DirHandle, 
*New, 
*Ucred); 


Description 

The hpss_LinkHandle function creates a new link to the file associated with ObjHandle, with the name 
New, taken relative to the directory specified by DirHandle. 
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Parameters 


ObjHandle 

DirHandle 

New 

Ucred 


Specifies the handle of the existing file to which the link is to be created. 
Handle to the parent directory. 

Specifies the path name of the new link. 

User credentials. 


Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix, or write 

permission is denied on the parent directory of the new link. 

EEXIST The object identified by New already exists. 

EFAULT The ObjHandle, DirHandle, or New parameter is a NULL pointer. 

EPERM The object specified by ObjHandle is a directory. 

EMLINK The number of links to the file named by ObjHandle would exceed the system- 

imposed limit. 

ENAMETOOLONG The length of the New argument exceeds the system-imposed path name limit or 

a path name component exceeds the system-imposed limit. 

ENOENT New points to a null string. 

ENOTDIR A component of the path prefix is not a directory. 

See Also 

hpssLink, hpssSymlink, hpssUnlink, hpssUnlinkHandle. 

Notes 


2.1.82. hpss_LoadThreadState 

Purpose 

Updates the user credentials and file or directory creation mask for the current thread's Client API state. 

Synopsis 

#include "hpss_api.h" 

int 

hpss_LoadThreadState( 

uid_t UserID, 

mode_t Umask, 

char *ClientFullName ) 


/* IN */ 
/* IN */ 
/* IN */ 


Description 
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The hpssLoadThreadState routine updates the user credentials and fileor directory creation mask found in 
the current thread's Client API state. 


Parameters 

UserlD Specifies the user ID for the user whose credentials are to be loaded. 

Umask Specifies the new file or directory creation mask. 

ClientFullName Specifies the client's fully qualified name. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

ENOENT Credentials for the specified user could not be obtained. 

See Also 

hpssLoadDefaultThreadState 

Notes 


None. 

2.1.83. hpss_LoadDefaultThreadState 

Purpose 

Special interface to allow well-behaved clients to manipulate the global thread state so that all threads will 
use the new state. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_LoadDefaultThreadState( 
uid_t UserlD, 

mode_t Umask, 

char *ClientFullName ) 


/* IN */ 
/* IN */ 
/* IN */ 


Description 

The hpss_LoadDefaultThreadState routine updates the global thread state so that all threads will use the 
new state. After this call, hpss_LoadThreadState routine is effectively disabled because for each new API 
the credentials are reloaded from the global thread state. 

Parameters 

UserlD Specifies the user ID for the user whose credentials are to be loaded. 

Umask Specifies the new file or directory creation mask. 

ClientFullName Specifies the client fully qualified name. 

Return Values 
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Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

ENOENT Credentials for the specified user could not be obtained. 

See Also 

hpssLoadThreadState 

Notes 


None. 


2.1.84. hpss_Lseek 

Purpose 

Set the current file offset for an open file, given a 32-bit value. 

Synopsis 

#include <unistd.h> 

#include "hpss_api.h" 
hpss_off_t 
hpss_Lseek( 

int Fildes, /* IN */ 

hpss_off_t Offset, /* IN */ 

int Whence ); /* IN */ 


Description 

The hpss_Lseek function sets the file offset for the open file handle, Fildes. Refer to POSIX. 1 for more 
detailed information. 

Parameters 

Fildes Specifies the open file handle for which the file offset is to be set. 

Offset Specifies the number of bytes to be used in calculating the new file offset - 

dependent on the value of Whence as to the final effect on the new file offset. 

Whence Specifies how to interpret the Offset parameter in setting the file pointer 

associated with the Fildes parameter. Values for the Whence parameter are as 
follows: 

SEEK SET - file offset set to Offset. 

SEEK CUR - file offset set to current offset plus Offset. 

SEEK END - file offset set to current end of file plus Offset. 

Return Values 

Upon successful completion, hpss_Lseek returns a nonnegative value representing the resulting offset as 
measured in bytes from the beginning the file. Otherwise, hpss_Lseek returns a negative value; the 
absolute value of which is equal to an ermo value set by POSIX. 1 lseek. 
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Error Conditions 


EBADF The specified file descriptor does not refer to an open file. 

EBUSY The file is currently in use by another client thread. 

EFBIG Could not represent the resulting offset in the return value. 

EINVAL The Whence parameter is invalid or the resulting offset would be invalid. 

ESTALE Connection to this file descriptor is no longer valid. 

See Also 

hpssRead, hpssWrite, hpssSetFileOffset. 

Notes 

None. 

2.1.85. hpss_Lstat 

Purpose 

Get file status (POSIX), returning status about a symbolic link if the named file is a symbolic link. 
Synopsis 

#include "hpss_api.h" 
int 

hpss_Lstat( 

char *Path, /* IN */ 

hpss_stat_t *Buf ); /* OUT */ 


Description 

The hpss_Lstat function obtains information about the file named by Path and returns it in the structure 
pointed to by Buf. Refer to POSIX. 1 for more detailed information. This function differs from hpss_Stat, 
however, in that if the named file is a symbolic link, information is returned about the link itself, not about 
the file to which the link points. If Path refers to a junction, the junction will be traversed. 

Parameters 

Path Points to the path name of the file being queried. 

Buf Points to an hpss stat t structure that will contain the information for the file. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX. 1 stat. 

Error Conditions 

EACCES Search permission is denied for a component of the path prefix. 

EFAULT The Path or Buf parameter is a NULL pointer. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 
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ENOENT 

ENOTDIR 


The named file does not exist, or the Path argument points to an empty string. 
A component of the Path prefix is not a directory. 


See Also 


hpssChown, hpssChmod, hpssUtime, hpssFileGetAttributes, hpssFileGetAttributesHandle, 
hpssFileGetAttributesSOID, hpssFileSetAttributes, hpssFileSetAttributesHandle, 
hpssFilesetAttributesSOID, hpssStat, hpssFstat, hpssGetListAttrs, hpssReadAttrs. 


None. 


2.1.86. hpss_Migrate 

Purpose 

Migrate a file from a specified level in the storage hierarchy. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Migrate( 
int 

unsigned32 
unsigned32 
u_signed64 

Description 

The hpss_Migrate routine migrates an open file from a level in the storage hierarchy, specified by 
SrcLevel. The Flags argument is used to control behavior of the request. 

Parameters 


Fildes, /* IN */ 

SrcLevel, /* IN */ 

Flags, /* IN */ 

*RetBytesMigrated ) ; /* OUT */ 


Specifies the file descriptor corresponding to the file to be migrated. 
Identifies the level in the storage hierarchy from which the data is to be 
migrated. 

Controls the behavior of the migrate request. Anticipated values include: 
HPSS MIGRATE FORCE - migrate data even with copies at lower levels. 

HPSSMIGRATEPURGEDATA - purge data after migration. 

HPSS MIGRATE NO COPY - do not migrate multiple copies. 
RetBytesMigrated Points to an area to contain the number of bytes migrated. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 


Fildes 

SrcLevel 

Flags 


EBADF The supplied file descriptor does not correspond to a file opened for writing. 
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EBUSY The specified file descriptor is in use. 

EFAULT The RetBytesMigrated parameter is a NULL pointer. 

EINVAL The Flags argument is invalid. 

EPERM The client does not have the appropriate privileges to issue explicit file 

migration requests. 

See Also 

hpssPurge, hpssStage. 

Notes 


None. 

2.1.87. hpss_Mkdir 

Purpose 

Create a directory. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Mkdir( 

char *Path, /* IN */ 

mode_t Mode ); /* IN */ 

Description 

The hpss_Mkdir function creates a new directory with the name Path. The file permission bits of the new 
directory are initialized by Mode and modified by the file creation mask of the thread. 

Parameters 

Path Specifies the path name to be used for the newly created directory. 

Mode Specifies permission bits to be used in setting the mode of the new directory. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX. 1 mkdir. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix, or write 

permission is denied on the parent directory of the directory to be created. 
EEXIST The named fde exists. 

EFAULT The Path parameter is a NULL pointer. 

EMLINK The link count of the parent directory would exceed the maximum allowed 

number of links. 
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ENAMETOOLONG 


The length of the Path argument exceeds the system-imposed limit, or a 
component of the pathname exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 


hpssMkdirHandle, hpssUmask, hpssRmdir. 


Notes 


None. 

2.1.88. hpss_MkdirHandle 

Purpose 

Create a directory. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_MkdirHandle( 

/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 
/* OUT */ 


ns_Obj Handle_t 

char 

mode_t 

sec_cred_t 

ns_Obj Handle_t 

hpss vattr t 


*ObjHandle, 
*Path, 

Mode, 

*Ucred, 

*HandleOut, 
*AttrOut) ; 


Description 

The hpss_MkdirHandle function creates a new directory with the name Path, taken relative to the 
directory indicated by ObjHandle. The directory permission bits of the new directory are initialized by 
Mode, and modified by the file creation mask of the thread. The newly created directory's object handle 
and attributes are returned in the areas pointed to by HandleOut and AttrOut respectively. 

Parameters 


ObjHandle 

Path 

Mode 

Ucred 

HandleOut 

AttrOut 


Handle of parent directory. 

Specifies the path name to be used for the newly created directory. 

Specifies permission bits to be used in setting the mode of the new directory. 
User credentials. If NULL, credentials in current thread context are used. 
New directory's object handle. 

Returned VFS attributes. 


Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX. 1 mkdir. 

Error Conditions 
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Search permission is denied on a component of the path prefix, or write 
permission is denied on the parent directory of the directory to be created. 

The named file exists. 

The Path parameter is a NULL pointer. 

The link count of the parent directory would exceed the maximum allowed 
number of links. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 

component of the pathname exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 

See Also 

hpssMkdir, hpssUmask, hpssRmdir, hpssRmdirHandle 

Notes 


EACCES 

EEXIST 

EFAULT 

EMLINK 


None. 

2.1.89. hpss_Open 

Purpose 

Optionally create and open an HPSS file. 

Synopsis 

#include <fcntl.h> 

#include "hpss_api.h" 
int 

IN */ 
IN */ 
IN */ 
IN */ 
IN */ 
OUT */ 


char 

int 

mode_t 

hpss_cos_hints_t 

hpss_cos_priorities_ 

hpss_cos_hints_t 


*Path, 

Oflag, 

Mode, 
*HintsIn, 
*HintsPri, 
*HintsOut ); 


/* 

/* 

/* 

/* 

/* 

/* 


Description 

The hpss_Open function establishes the connection between a file, named by the Path argument, and a file 
handle. If O CREAT is specified in Oflag and the file does not exist, an attempt will be made to create the 
file. 

Parameters 

Path Names the file to be opened or created. 
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Oflag Specifies the file status and file access modes to be assigned. Applicable values 

given below may be OR'ed together. Refer to POSIX. 1 for specific behavior. 
ORDONLY 

OWRONLY 

ORDWR 

OAPPEND 

OCREAT 

OEXCL 

OTRUNC 

0_NONBLOCK 

Mode Specifies the file mode for a file that is created as a result of O CREAT. 

Hintsln Points to an hpss_cos_hints_t structure which provides allocation hints to 

HPSS as to the expected structure or access of the file. This argument may be a 
NULL pointer if the default COS is to be used. This parameter is only used 
during file creation. 

HintsPri Points to an hpss_cos_priorities_t structure which provides the relative 

priorities associated with the fields contained in the HintsPri structure. This 
parameter is only used during file creation, and may be a NULL pointer. The 
priority will be set to REQUIREDPRIORITY if HintsPri is NULL. 

HintsPri Points to an hpss_cos_priorities_t structure which provides the relative 

riorities associated with the fields contained in the HintsPri structure. This 
parameter is only used during file creation, and may be a NULL pointer. The 
priority will be set to REQUIREDPRIORITY if HintsPri is NULL. 

HintsOut Points to an hpss_cos_hints_t structure which will contain the values actually 

used when the file is created. This argument may be a NULL pointer if the 
returned values are to be ignored. This parameter is only used during file 
creation. 

Return Values 

Upon successful completion, hpss_Open returns a nonnegative value that is the newly allocated file handle. 

Otherwise, hpss_Open returns a negative value, the absolute value of which is equal to an ermo value set 

by POSIX. 1 open. 

Error Conditions 

EACCES One of the following conditions occurred: 

• Search permission is denied on a component of the path prefix. 

• The file exists and the permissions specified by Oflag are denied. 

• The file doesn't exist and write permission is denied for the parent 
directory of the file to be created. 

• O TRUNC is specified and write permission is denied. 

EEXIST O CREAT and OEXCL are set and the named file exists. 
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EFAULT The Path parameter is a NULL pointer. 

EINPROGRESS The file is currently being staged. The open should be retried at a later time. 

EINVAL OJlag is not valid, or one or more values input in the Hintsln parameter is 

invalid. 

EISDIR The named file is a directory. Note that opening directories via hpss_Open is 

not supported in any mode. 

EMFILE The client open file table is already full. 

ENFILE Too many files are open in the system. 

ENAMETOOLONG The length of the Path string exceeds the system-imposed path name limit or a 
path name component exceeds the system-imposed limit. 

ENOENT The named file does not exist and the O CREAT flag was not specified, or the 

Path argument points to an empty string. 

ENOMEM Memory could not be allocated for the new path name. 

ENOTDIR A component of the Path prefix is not a directory. 


See Also 


hpssOpenHandle, hpssClose, hpssUmask, hpssOpenBitfile, hpssCreate, hpssCreateHandle, 
hpssReopenBitfile. 


Note that opening directories with hpss_Open is not supported. 

2.1.90. hpss_OpenBitfile 

Purpose 

Open an HPSS bitfile, specified by bitfile ID. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_OpenBitfile( 


hpssoid_t 

*B±tF±leID, 

/* 

IN 

*/ 

int 

OFlag, 

/* 

IN 

*/ 

sec_cred_t 

*Ucred, 

/* 

IN 

*/ 

hps s_authz_token_t 

*AuthzTicket ); 

/* 

IN 

*/ 


Description 

The hpss_OpenBitfile routine attempts to open the bitfile identified by BitFilelD. Note that this routine 
cannot be used to create a bitfile; rather, hpss_Create, hpss_CreateHandle, hpss_CreateDMHandle, 
hpss_Open or hpss_OpenHandle must be used for this purpose. 

Parameters 

BitFilelD Points to bitfile identifier. The BitfilelD is usually obtained using 

hp ssFileGetAttributes. 
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Oflags 


Specifies file status and file access modes to be assigned. Applicable values 
given below may be OR'ed together. Refer to POSIX. 1 for specific behavior. 

ORDONLY 
OWRONLY 
ORDWR 
OAPPEND 
OTRUNC 

Ucred Points to client's user credentials. 

AuthzTicket Points to client's authorization for this file. 

Return Values 

Upon successful completion, a nonnegative file descriptor is returned. Otherwise, a negative value is 
returned, the absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EACCES The client does not have permission for the requested file access. 

EFAULT The BitFilelD or AuthzTicket parameter is a NULL pointer. 

EINPROGRESS The file is currently being staged. The open should be retried at a later time. 

EINVAL Oflag is not valid. 

EMFILE The client file table is already full. 

ENFILE Too many bitfiles are already open in the system. 

ENOENT No entry exists for the specified bitfile ID. 

See Also 

hpssCreate, hpss CreateHandle, hpss CreateDMHandle, hpss Open, hpss OpenHandle, 
hpss OpenBitfileVAttrs, hpss ReopenBitfile, hpss Close 

Notes 

The user cannot generate a valid Authorization Ticket. Authorization Tickets are typically used by 
authorized clients. Unauthorized clients should pass a zero value for AuthzTicket. 

2.1.91. hpss_OpenBitfileVAttrs 

Purpose 

Open an HPSS bitfile, specified by its file attributes structure. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_OpenBitfileVAttrs( 

hpss_vattrs_t *FileAttrs, /* IN */ 

int OFlag, /* IN */ 
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sec_cred_t 

hpss_authz_token_t 

hpss_cos_hints_t 


*Ucred, /* IN */ 

*AuthzT±cket, /* IN */ 

*HintsOut ); /* OUT */ 


Description 

The hpss_OpenBitfileVAttrs function is a simple interface for opening a bitfile using existing bitfile 
attributes and authorization ticket. This function is different from other open calls in that it only obtains an 
open context, without making any extra path traverse or get attribute calls. 

Parameters 


FileAttrs 

Oflags 


Ucred 

AuthzTicket 

HintsOut 


Points to the file's attributes structure. 

Specifies file status and file access modes to be assigned. Applicable values 
given below may be OR'ed together. Refer to POSIX. 1 for specific behavior. 
ORDONLY 

OWRONLY 

ORDWR 

OAPPEND 

OTRUNC 

Points to client's user credentials. 

Points to client's authorization for this file. 

Pointer to hints used for opening file. 


Return Values 

Upon successful completion, a nonnegative file descriptor is returned. Otherwise, a negative value is 
returned, the absolute value of which is equal to an ermo value defined below. 

Error Conditions 


EACCES The client does not have permission for the requested file access. 

EFAULT The BitFilelD or AuthzTicket parameter is a NULL pointer. 

EINPROGRESS The file is currently being staged. The open should be retried at a later time. 

EINVAL Qflag is not valid. 

EMFILE The client file table is already full. 

ENFILE Too many bitfiles are already open in the system. 

ENOENT No entry exists for the specified bitfile ID. 


See Also 


hpss Create, hpss CreateHandle, hpss CreateDMHandle, hpss Open, hpss OpenHandle, 
hpss OpenBitfile, hpss ReopenBitflle, hpss Close 


The user cannot generate a valid Authorization Ticket. Authorization Tickets are typically used by 
authorized clients. Unauthorized clients should pass a zero value for AuthzTicket. 
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2.1.92. hpss_OpenHandle 

Purpose 

Optionally create and open an HPSS file relative to a given directory. 

Synopsis 

#include <fcntl.h> 

#include "hpss_api.h" 
int 

hpss_OpenHandle( 

ns_Obj Handle_t 
char 
int 

mode_t 
sec_cred_t 
hpss_cos_hints_t 
hpss_cosj?riorities_t 
hpss_cos_hints_t 
hps s_vattr_t 
hps s_authz_token_t 

Description 

The hpss_OpenHandle function establishes the connection between a file, named by the Path argument 
taken relative to the directory specified by ObjHandle, and a file handle. If OCREAT is specified in 
Oflag and the file does not exist, an attempt will be made to create the file. 

Parameters 

ObjHandle Parent object handle, the parent directory. 

Path Names the file to be opened or created. 

Oflags Specifies the file status and file access modes to be assigned. Applicable values 

given below may be OR'ed together. Refer to POSIX. 1 for specific behavior. 
ORDONLY 

0_WR0NLY 

ORDWR 

OAPPEND 

OCREAT 

OEXCL 

OTRUNC 

Mode Specifies the file mode for a file that is created as a result of O CREAT. 

Ucred Points to client's user credentials. 

Hintsln Points to an hpss_cos_hints_t structure which provides allocation hints to 

HPSS as to the expected structure or access of the file. This argument may be a 
NULL pointer if the default COS is to be used. This parameter is only used 
during file creation. 


*ObjHandle, /* IN */ 

*Path, /* IN */ 

Oflag, /* IN */ 

Mode, /* IN */ 

*Ucred, /* IN */ 

*HintsIn, /* IN */ 

*HintsPri, /* IN */ 

*HintsOut, /* OUT */ 

*AttrsOut, /* OUT */ 

*AuthzTicket) ; /* OUT */ 
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HintsPri 


HintsOut 


AttrsOut 


Points to an hpss_cos_priorities_t structure which provides the relative 
priorities associated with the fields contained in the HintsPri structure. This 
parameter is only used during file creation, and may be a NULL pointer. The 
priority will be set to REQUIREDPRIORITY if HintsPri is NULL. 

Points to an hpss_cos_hints_t structure which will contain the values actually 
used when the file is created. This argument may be a NULL pointer if the 
returned values are to be ignored. This parameter is only used during file 
creation. 

Returned file attributes. 


AuthzTicket Client Authorization. 


Return Values 

Upon successful completion, hpss_OpenHandle returns a nonnegative value that is the newly allocated file 
handle. Otherwise, hpss_OpenHandle returns a negative value; the absolute value of which is equal to an 
ermo value set by POSIX. 1 open. 

Error Conditions 


EACCES One of the following conditions occurred: 

• Search permission is denied on a component of the path prefix. 

• The file exists and the permissions specified by Oflag are denied. 

• The file doesn't exist and write permission is denied for the parent 
directory of the file to be created. 

• O TRUNC is specified and write permission is denied. 

EEXIST OCREAT and O EXCL are set and the named file exists. 

EFAULT The Path parameter is a NULL pointer. 

EINPROGRESS The file is currently being staged. The open should be retried at a later time. 

EINVAL Oflag is not valid, or one or more values input in the Hintsln parameter is 

invalid. 

EISDIR The named file is a directory. Note that opening directories via hpss_Open is 

not supported in any mode. 

EMFILE The client open file table is already full. 

ENFILE Too many files are open in the system. 

ENAMETOOLONG The length of the Path string exceeds the system-imposed path name limit or a 
path name component exceeds the system-imposed limit. 

ENOENT The named file does not exist and the O CREAT flag was not specified, or the 

Path argument points to an empty string. 

ENOSPC Resources could not be allocated for the new file. 

ENOTDIR A component of the Path prefix is not a directory. 


See Also 


hpssOpen, hpssClose, hpssUmask, hpssOpenBitfile, hpssCreate, hpssCreateHandle, 
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hpssReopenBitfile. 


Notes 


Opening directories with hpss_OpenHandle is not supported. Use hpss_Opendir instead. 

2.1.93. hpss_Opendir 

Purpose 

Open an HPSS directory. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Opendir( 

char *DirName ); /* IN */ 


Description 

The hpss_Opendir function opens a directory stream corresponding to the directory named by DirName. 
The directory stream is positioned at the first entry in the directory. 

Parameters 

DirName Specifies the path name of the directory to be opened. 

Return Values 

Upon successful completion, hpss_Opendir returns a nonnegative value that is the newly allocated 
directory stream handle. Otherwise, hpss_Opendir returns a negative value; the absolute value of which is 
equal to an ermo value set by POSIX.l opendir. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix, or read 

permission is denied on the directory itself. 

EFAULT The DirName parameter is a NULL pointer. 

EMFILE The open file table is already full. 

ENAMETOOLONG The length of the DirName argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the DirName argument points to an empty 

string. 

ENOTDIR A component of DirName is not a directory. 


See Also 


hpss Readdir, hpss Rewinddir, hpss Closedir. 

Notes 


The return value is changed from POSIX, primarily to make handling open directories and files in the client 
API consistent. 


HPSS Programmer's Reference 
Release 6.2 (Revision 2.0) 


July 2008 


120 



2.1.94. hpss_OpenWithHints 

Purpose 

Open an HPSS file using hints for COS and priorities. 

Synopsis 

#include "hpss_posix_api.h" 
int 

hpss_OpenWithHints( 

char *P ath, /* IN */ 

int Oflag, /* IN */ 

mode_t Mode, /* IN */ 

hpss_cos_hints_t *HintsIn, /* IN */ 

hpss_cosj?riorities_t *H±ntsPr±, /* IN */ 

hpss_cos_hints_t *HintsOut) ; /* OUT */ 

Description 

The hpss_OpenWithHints routine opens an HPSS file using input hints to define the COS and priorities. 

Parameters 

Path Specifies the path/name of the HPSS file. 

Oflag Specifies the file access. 

ORDONLY 

OWRONLY 

ORDWR 

OAPPEND 

OCREAT 

OEXCL 

OTRUNC 

Mode If O CREAT is specified and a file is created, this argument gives the mode 

used for determining the file mode for the created file. 

Hintsln Pointer to structure defining client preferences for class of service. 

HintsPri Pointer to structure defining the priorities of each COS structure field. 

HintsOut Pointer to structure defining COS with which file was created. 

Return Values 

Upon successful completion hpss_OpenWithHints returns a non-negative value representing the open file 
descriptor. If an error is encountered, a negative value will be returned whose absolute value indicates the 
error condition. 

Error Conditions 

EFAULT Null Path pointer. 

ENOENT Path points to null string. 
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ENOMEM Memory allocation failure. 

EINVAL Invalid hints parameters. 


See Also 


hpssOpen, hpssPosixOpen, hpssPosixCreate, hpssCreateWithHints, hpssPosixLseek 


Notes 


The hpss_OpenWithHints function is identical to hpss_Open. It is created at the request of a customer. 

2.1.95. hpss_PIOEnd 

Purpose 

End a parallel I/O transfer. 

Synopsis 

int 

hpss_PIOEnd( 

hpss_pio_grp_t StripeGroup) /* IN */ 


Description 

This function verifies that the StripeGroup is valid and completes the I/O for the group if called by the 
coordinating side. 

Parameters 

StripeGroup Identifies the group of participants involved in the stripe group. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EINVAL Invalid I/O stripe group input. 

ENOMEM Out of memory for stack entry. 

See Also 

hpss PIOStart, hpss PIORegister, hpssPIOExecute, hpss PIOExportGrp, hpss PIOImportGrp 

Notes 


None. 

2.1.96. hpss_PIOExecute 

Purpose 


Begin a parallel TO transfer. 

Synopsis 

int 

hpss_PIOExecute( 

int Fd, /* IN */ 
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u_signed64 FileOffset, /* IN */ 

u_signed64 Size, /* IN */ 

hpss_pio_grp_t StripeGroup, /* IN */ 

hpss_pio_gapinfo_t *GapInfo, /* OUT */ 

u_signed64 *BytesMoved) /* OUT */ 

Description 

This function is used by a transfer coordinator to begin a parallel I/O data transfer operation. 

Parameters 

Fd An open HPSS File descriptor. 

FileOffset The fde offset. 

Size Size of the TO. 

StripeGroup The stripe group. 

Gaplnfo Pointer to information concerning a sparse file. 

BytesMoved Number of bytes moved with this transfer. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EINVAL Invalid argument. 

ENOMEM Not enough memory for stack entry. 

See Also 

hpss PIOStart, hpss PIORegister, hpss PIOEnd, hpss PIOExportGrp, hpss PIOImportGrp 

Notes 

None. 

2.1.97. hpss_PIOExportGrp 

Purpose 

Convert group I/O data to raw data. 

Synopsis 

int 

hpss_PIOExportGrp( 

hpss_pio_grp_t StripeGroup 

void **Buffer, 

unsigned int *BufLength) 

Description 

This function is used by a transfer coordinator to convert parallel 10 group context data into raw data that is 
suitable to transfer across the network. 


/* IN */ 
/* OUT */ 
/* OUT */ 
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Parameters 

StripeGroup The I/O stripe group. 

Buffer Pointer to the output raw data buffer pointer. 

BufLength Pointer to the length of Buffer. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EFAULT Buffer or BufLength pointer is NULL. 

EINVAL Invalid StripeGroup input. 

ENOMEM Not enough memory to allocate output buffer. 

See Also 

hpssPIOEnd, hpssPIOStart, hpssPIORegister, hpss PIOImportGrp, hpss Execute 

Notes 


2.1.98. hpss_PIOImportGrp 

Purpose 

Convert raw parallel MO group context data. 

Synopsis 

int 

hpss_PIOImportGrp( 

void *Buffer, /* IN */ 

unsigned int BufLength, /* IN */ 

hpss_pio_grp_t *StripeGroup) /* OUT */ 


Description 

This function converts raw parallel I/O group data into a format suitable for the hpss_PIORegister 
function. 

Parameters 

Buffer Pointer to the input raw data buffer. 

BufLength Length of the raw data buffer. 

StripeGroup Pointer to the converted stripe group data. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EINVAL Invalid parameter or bad checksum. 
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ENOMEM Not enough memory to allocate for the stripe group structure. 

See Also 

hpssPIOExecute, hpssPIOEnd, hpssPIORegister, hpssPIOExportGrp, hpssPIOStart 

Notes 

None. 

2.1.99. hpss_PIORegister 

Purpose 

Register an I/O callback function. 

Synopsis 

int 

hpss_PIORegister( 

unsigned32 StripeElement, /* IN */ 

unsigned32 DataNetAddr, /* IN */ 

void *DataBuffer, /* IN */ 

unsigned32 DataBufLen, /* IN */ 

hpss_pio_grp_t StripeGroup, /* IN */ 

hpss_pio_cb_t IOCallback, /* IN */ 

void *IOCallbackArg)/* IN */ 

Description 

This function is used by a parallel I/O participant to register a callback function. 

Parameters 

StripeElement Element of the data stripe. 

DataNetAddr Element of the data stripe. 

DataBuffer Buffer for the MO. 

DataBufLen Length of the data buffer. 

StripeGroup The I/O stripe group. 

IOCallback I/O callback function. 

IOCallbackArg Pointer to the callback argument. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EINVAL Invalid argument or checksum. 

ENOMEM Not enough memory to allocate stripe group. 

See Also 

hpss PIOStart, hpss PIOEnd, hpss PIOExecute, hpss PIOImportGrp, hpss ExportGrp 
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2.1.100. hpss_PIOStart 

Purpose 


Start a new parallel I/O group data transfer. 

Synopsis 

int 

hpss_PIOStart( 

hpss_pio_params_t *InputParams, /* IN */ 

hpss_pio_grp_t *StripeGroup) /* OUT */ 


Description 

This function is used by a transfer coordinator to start a new parallel I/O group context. 

Parameters 

InputParams Parameters defining the type of transport, stripe width, number of data elements 

StripeGroup Pointer to the stripe group. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EFAULT StripeGroup is NULL. 

EINVAL Invalid or NULL InputParams. 

ENOMEM Not enough memory to allocate stripe group. 

See Also 


hpssPIOExecute, hpss PIOEnd, hpssPIOExportGrp, hpss PIOImportGrp, hpss PIORegister 

Notes 


None. 


2.1.101. hpss_Purge 

Purpose 


Purge a piece of a file from a specified level in the storage hierarchy. 


Synopsis 


#include "hpss_api.h" 
int 

hpss_Purge( 
int 

u_signed64 
u_signed64 
unsigned32 
unsigned32 
u_signed64 


Fildes, 

Offset, 

Length, 
StorageLevel, 
Flags, 

*RetBytesPurged ) ; 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 
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Description 

The hpss_Purge routine purges part of an open file, specified by Fildes, Offset and Length from a level in 
the storage hierarchy, specified by StorageLevel. The Flags argument is used to control behavior of the 
request. 

Parameters 

Fildes Specifies the file descriptor corresponding to the file to be purged. 

Offset Specifies the offset of the start of the data to be purged. Currently must be 0. 

Length Specifies the length of the data to be purged. Currently must be 0. 

StorageLevel Identifies the level in the storage hierarchy from which the data is to be purged. 

Flags Controls the behavior of the purge request. Valid values include: 

BFSPURGEALL - purge the entire file (required). 

RetBytesPurged Points to an area that will contain the number of bytes purged. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EBADF The supplied file descriptor does not correspond to an open file. 

EBUSY The specified file descriptor is in use. 

EFAULT The RetBytesPurged parameter is a NULL pointer. 

EINVAL he Flags, Offset or Length argument is invalid. 

EPERM The client does not have the appropriate privileges to perform explicit purge 

operations. 

See Also 

hpss Migrate, hpss Stage, hpss PurgeLock 

Notes 

None. 

2.1.102. hpss_PurgeLock 

Purpose 

Lock (or unlock) a file into the top level of its hierarchy. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_PurgeLock( 

int Fildes, /* IN */ 

purgelock_flag_t Flag ); /* IN */ 
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Description 

The hpss_PurgeLock routine either locks a file in the top level of its hierarchy from being purged or 
removes an existing lock. 

Parameters 

Fildes Specifies the file descriptor corresponding to the file to be locked/unlocked. 

Flag Controls whether the request locks or unlocks the file. Possible values are: 

PURGELOCK - Purge lock the file 

PURGEUNLOCK - Purge unlock the file. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EBADF The supplied file descriptor does not correspond to an open file. 

EBUSY The specified file descriptor is in use. 

ESTALE The connection for this entry is not valid. 

See Also 

hpssPurge. 

Notes 

None. 

2.1.103. hpss_PurgeLoginCred 

Purpose 

Purge login credentials set by hpss_SetLoginCred. 

Synopsis 

#include "hpss_api.h" 
void 

hpss_PurgeLoginCred(void); 

Description 

This routine purges the login credentials established by the routine hpss_SetLoginCred. 

Parameters 

None. 

Return Values 

None. 

Error Conditions 
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None. 


See Also 

hpssSetLoginCred. 

Notes 

None. 

2.1.104. hpss_Read 

Purpose 

Read a contiguous section of an HPSS file, beginning at the current file offset, into a client buffer. 

Synopsis 

#include "hpss_api.h" 
ssize_t 
hpss_Read( 

int Fildes, 

void *Buf, 

size_t Mbyte ) 

Description 

The hpss_Read function attempts to read Nbyte bytes from the file associated with the open file handle, 
Fildes, into the client buffer pointed to by Buf. 

Parameters 

Fildes 

Buf 
Nbyte 

Return Values 

Upon successful completion, hpss_Read returns a nonnegative value that is the number of bytes read, 
including any holes encountered. Otherwise hpss_Read returns a negative value, the absolute value of 
which is equal to an ermo value set by POS1X.1 read. 

Error Conditions 

EBADF The specified file descriptor does not correspond to a file opened for reading. 

EBUSY The file is currently in use by another client thread. 

EFAULT The Buf parameter is NULL. 

ElO An input/output or HPSS internal error occurred. 

See Also 

hpss Open, hpss OpenHandle, hpss OpenBitflle, hpss OpenBitfileVAttrs, hpss OpenBitfileHandle, 
hpss Write, hpss Lseek, hpss SetFileOffset, hpss ReadList, hpss WriteList. 


Specifies the open file handle associated with the file from which data is to be 
read. 

Point to a buffer where the data is to be placed. 

Specifies the number of bytes to be read. 


/* IN */ 
/* IN */ 
/* IN */ 
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Notes 


None. 

2.1.105. hpss_ReadAttrs 

Purpose 

Read directory entries and optionally return entry attributes. 

Synopsis 

#include "hpss_api.h 
int 

hpss_ReadAttrs( 
int 

u_signed64 
unsigned32 
unsigned32 
unsigned32 
u_signed64 
ns_DirEntry_t 

Description 

The hpss_ReadAttrs routine returns a list of directory entries, which optionally includes file or directory 
attributes. 

Parameters 

Dirdes Specifies the open directory stream handle corresponding to the directory being 

read. 

Ojfsetln Specifies the starting directory offset. If zero, the list will be from the 

beginning of the directory. 

BufferSize Specifies the size of the buffer pointed to by DirentPtr, in bytes. The maximum 

number of entries that fit in the buffer will be returned, until the end of the 
directory is reached. 

GetAttributes Indicates, if nonzero, that attributes will be returned with the directory entries. 

End Points to an area that will contain an indication of whether the last entry is 

returned in the current list. 

OjfsetOut Points to an area that will contain the directory offset at the end of the returned 

list. This value can be supplied to a subsequent call to continue with the next 
directory entry. 

DirentPtr Points to a buffer to hold the returned list of directory entries and attributes. 

Return Values 

Upon successful completion, the return value indicates the number of directory entries in the returned list. 
Otherwise, a negative value is returned, the absolute value of which is equal to an ermo value defined 
below. 

Error Conditions 


Dirdes, /* IN */ 

Offsetln, /* IN */ 

BufferSize, /* IN */ 

GetAttributes, /* IN */ 

*End, /* OUT */ 

*OffsetOut, /* OUT */ 

*DirentPtr ); /* OUT */ 
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EBADF 

EBUSY 

EFAULT 

EINVAL 


See Also 


The specified directory descriptor does not refer to an open directory. 
The directory is currently in use by another client thread. 

The DirentPtr, End or OffsetOut parameter is a NULL pointer. 

The Buffer Size parameter is zero. 


hpssReadAttrsHandle, hpssOpendir, hpssClosedir. 

Notes 


Calling hpss_ReadAttrs does not affect the directory offset or cached directory entries that are manipulated 

via hpss Readdir and hpss Rewinddir. 


2.1.106. hpss_ReadAttrsHandle 

Purpose 

Read directory entries and optionally return entry attributes. 

Synopsis 

#include "hpss_api.h" 
int 

hpss ReadAttrsHandle( 

/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 
/* OUT */ 
/* OUT */ 


ns_Obj Handle_t 

u_signed64 

sec_cred_t 

unsigned32 

unsigned32 

unsigned32 

u_signed64 

ns_DirEntry_t 


*ObjHandle, 

Offsetln, 

*Ucred, 

BufferSize, 

GetAttributes, 

*End, 

*OffsetOut, 
*DirentPtr ); 


Description 

The hpss_ReadAttrsHandle routine returns a list of directory entries, which optionally includes file or 


directory attributes. 


Parameters 


ObjHandle 

The directory object handle. 

Offsetln 

Specifies the starting directory offset. If zero, the list will be from the 
beginning of the directory. 

Ucred 

User credentials. If NULL, the credentials in the current thread context are 
used. 

BufferSize 

Specifies the size of the buffer pointed to by DirentPtr, in bytes. The maximum 
number of entries that fit in the buffer will be returned, until the end of the 
directory is reached. 

GetAttributes 

Indicates, if nonzero, that attributes will be returned with the directory entries. 

End 

Points to an area that will contain an indication of whether the last entry is 
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returned in the current list. 


OffsetOut Points to an area that will contain the directory offset at the end of the returned 

list. This value can be supplied to a subsequent call to continue with the next 
directory entry. 

DirentPtr Points to a buffer to hold the returned list of directory entries and attributes. 

Return Values 

Upon successful completion, the return value indicates the number of directory entries in the returned list. 
Otherwise, a negative value is returned, the absolute value of which is equal to an ermo value defined 
below. 

Error Conditions 

EBADF The specified directory descriptor does not refer to an open directory. 

EBUSY The directory is currently in use by another client thread. 

EFAULT The DirentPtr, End or OffsetOut parameter is a NULL pointer. 

EINVAL The ObjHandle pointer is NULL or the BufferSize parameter is zero. 

See Also 

hpss ReadAttrs, hpss ReadRawAttrsHandle, hpss Opendir, hpss Closedir. 

Notes 


Calling hpss_ReadAttrsHandle does not affect the directory offset or cached directory entries that are 
manipulated via hpss Readdir, hpss ReaddirHandle, and hpss Rewinddir. 

2.1.107. hpss_Readdir 

Purpose 

Read a directory entry. 

Synopsis 

#include <dirent.h> 

#include "hpss_api.h" 
int 

hpss_Readdir( 

int DirDes, 

hpss_dirent_t *DirentPtr ) 


/* IN */ 
/* OUT */ 


Description 

The hpss_Readdir function returns a structure, DirentPtr, representing the directory entry at the current 
position in the open directory stream. Reference the hpssdirent_t structure definition for more detailed 
information. 

Parameters 

DirDes Specifies the open directory stream handle corresponding to the directory being 

read. 
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DirentPtr 


Points to a structure that will contain the directory entry information. 


Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX. 1 readdir. 

Error Conditions 

EBADF The specified directory descriptor does not refer to an open directory. 

EBUSY The directory is currently in use by another client thread. 

EFAULT The DirentPtr parameter is a NULL pointer. 

See Also 

hpss Opendir, hpss Rewinddir, hpss Closedir. 

Notes 


1. hpss_Readdir is altered from POSIX. 1 readdir to be more consistent with other FIPSS calls. These 
differences are that hpss_Readdir 1) accepts an integer directory stream handle (see hpss_Opendir) 
and 2) moves the returned structure pointer to the argument list rather than the return value. 

2. When the end of the directory is encountered, the d name field will be set to an empty string, and the 
d_namelen field will be set to zero. These fields are in DirentPtr structure. 

2.1.108. hpss_ReaddirHandle 

Purpose 

Read a directory entry. 

Synopsis 

#include <dirent.h> 

#include "hpss_api.h" 
int 

hpss_ReaddirHandle( 
ns_Obj Handle_t 
u_signed64 
sec_cred_t 
unsigned32 
unsigned32 
u_signed64 
hpss_dirent_t 


*ObjHandle, 

Offsetln, 

*Ucred, 

BufferSize, 

*End, 

*OffsetOut, 
*DirentPtr ); 


7 

IN */ 


/* IN */ 
/* IN */ 
/* OUT */ 
/* OUT */ 


/* OUT */ 


Description 

The hpss_ReaddirHandle function returns a structure, DirentPtr, representing the directory entry at the 
current position in the open directory stream. Reference the hpss dirent t structure definition for more 
detailed information. The function also returns the resulting directory position in OffsetOut, and an end of 
directory in End. 

Parameters 
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ObjHandle 


Specifies the open directory object handle corresponding to the directory being 
read. 

Offsetln Current directory position. 

Ucred User credentials. If NULL, the credentials in the current thread context are 

used. 

Buffer Size Size of buffer pointed to by DirentPtr. 

End End of directory indicator. 

OffsetOut Resulting directory position. 

DirentPtr Points to a structure that will contain the directory entry information. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX. 1 readdir. 

Error Conditions 

EBADF 
EBUSY 
EFAULT 
EINVAL 

See Also 

hpss Opendir, hpss Rewinddir, hpss Closedir. 

Notes 

1. hpss_Readdir is altered from POSIX. 1 readdir to be more consistent with other HPSS calls. These 
differences are that hpss_Readdir 1) accepts an integer directory stream handle (see hpss_Opendir) 
and 2) moves the returned structure pointer to the argument list rather than the return value. 

2. When the end of the directory is encountered, the d name field will be set to an empty string, and the 
d namelen field will be set to zero. These fields are in DirentPtr structure. 

2.1.109. hpss_Readlink 

Purpose 

Read the value of a symbolic link (i.e., the data stored in the symbolic link). 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Readlink( 

char *Path, /* IN */ 

char *Contents, /* OUT */ 

size_t BufferSize ); /* IN */ 

Description 


The specified directory descriptor does not refer to an open directory. 
The directory is currently in use by another client thread. 

One of the End, OffsetOut, or DirentPtr parameters is NULL. 
BufferSize is zero or ObjHandle is NULL. 
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The hpss_Readlink routine returns the value of a symbolic link (not including any terminating null 
character) specified by Path into the buffer specified by Contents. The size of the buffer is specified by 
BufferSize. 


Parameters 

Path Specifies the name of the symbolic link to be read. 

Contents Points to buffer to contain the value of the symbolic link. 

BufferSize Specifies the size of the buffer pointed to by Contents. 

Return Values 

Upon successful completion, the length of the symbolic link name is returned. Otherwise, a negative value 
is returned, the absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix, or read 

permission is denied on the symbolic link. 

EFAULT The Path or Contents parameter is a NULL pointer. 

EINVAL The specified file is not a symbolic link. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The specified path name does not exist. 

ENOTDIR A component of the Path prefix is not a directory. 

ERANGE The size of the Contents buffer is not big enough to contain the contents of the 

symbolic link or the value of the BufferSize parameter is zero. 

See Also 

hpssReadlinkHandle, hpssSymlink, hpssSymlinkHandle 

Notes 

None. 

2.1.110. hpss_ReadlinkHandle 

Purpose 

Read the value of a symbolic link (i.e., the data stored in the symbolic link). 

Synopsis 


#in< 

:lude "hpss_api.h" 




int 





hpss 

3 ReadlinkHandle( 





ns_Obj Handle_t 

*ObjHandle, 

/* 

IN */ 


char 

*Path, 

/* 

IN */ 


char 

*Contents, 

/* 

OUT */ 


size_t 

BufferSize ) ; 

/* 

IN */ 


sec_cred_t 

* Ucred) 

/* 

IN */ 
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Description 

The hpss_ReadlinkHandle routine returns the value of a symbolic link (not including any terminating null 
character) specified by Path into the buffer specified by Contents. The symbolic link is taken relative to 
ObjHandle. The size of the buffer is specified by BufferSize. 

Parameters 


ObjHandle 

Path 

Contents 

BufferSize 

Ucred 


Parent object handle. 

Specifies the name of the symbolic link to be read. 

Points to buffer to contain the value of the symbolic link. 

Specifies the size, in bytes, of the buffer pointed to by Contents. 

User credentials. If NULL, the credentials in the current thread context are 
used. 


Return Values 

Upon successful completion, the length of the symbolic link name is returned. Otherwise, a negative value 

is returned, the absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix, or read 

permission is denied on the symbolic link. 

EFAULT The ObjHandle, Path or Contents parameter is a NULL pointer. 

EINVAL The specified file is not a symbolic link. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 

component of the path name exceeds the system-imposed limit. 

ENOENT The specified path name does not exist. 

ENOTDIR A component of the Path prefix is not a directory. 

ERANGE The size of the Contents buffer is not big enough to contain the contents of the 

symbolic link or the value of the BufferSize parameter is zero. 


See Also 


hpssReadlink, hpssSymlink, hpssSymlinkHandle 

2.1.111. hpss_ReadRawAttrsHandle 

Purpose 

Read directory entries and optionally return entry attributes. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_ReadRawAttrsHandle( 

ns_ObjHandle_t * ObjHandle, /* IN */ 

u_signed64 Offsetln, /* IN */ 
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sec_cred_t 

unsigned32 

unsigned32 

unsigned32 

u_signed64 

ns_DirEntry_t 


*Ucred, 
BufferSize, 
GetAttributes , 
*End, 

*OffsetOut, 
*DirentPtr ); 


/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 
/* OUT */ 
/* OUT */ 


Description 

The hpss_ReadRawAttrsHandle routine returns a list of directory entries, which optionally includes file or 
directory attributes. 

Parameters 

ObjHandle 
Offsetln 

Ucred 

BufferSize 

GetAttributes 
End 

OffsetOut 

DirentPtr 

Return Values 

Upon successful completion, the return value indicates the number of directory entries in the returned list. 
Otherwise, a negative value is returned, the absolute value of which is equal to an ermo value defined 
below. 

Error Conditions 

EBADF The specified directory descriptor does not refer to an open directory. 

EBUSY The directory is currently in use by another client thread. 

EFAULT The DirentPtr, End or OffsetOut parameter is a NULL pointer. 

EINVAL The ObjHandle pointer is NULL or the BufferSize parameter is zero. 

See Also 

hpss ReadAttrs, hpss ReadAttrsHandle, hpss Opendir, hpss Closedir. 

Notes 

1. Calling hpss_ReadRawAttrsHandle does not affect the directory offset or cached directory entries that 


The directory object handle. 

Specifies the starting directory offset. If zero, the list will be from the begining 
of the directory. 

User credentials. If NULL, the credentials in the current thread context are 
used. 

Specifies the size of the buffer pointed to by DirentPtr, in bytes. The maximum 
number of entries that fit in the buffer will be returned, until the end of the 
directory is reached. 

Indicates, if nonzero, that attributes will be returned with the directory entries. 
Points to an area that will contain an indication of whether the last entry is 
returned in the current list. 

Points to an area that will contain the directory offset at the end of the 
returned list. This value can be supplied to a subsequent call to continue with 
the next directory entry. 

Points to a buffer to hold the returned list of directory entries and attributes. 
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are manipulated via hpssReaddir, hpssReaddirHandle, and hpssRewinddir. 
2. This routine will not follow HPSS junctions. 

2.1.112. hpss_Rename 

Purpose 

Rename a file or directory. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Rename( 

char *01d, /* IN */ 

char *New ); /* IN */ 


Description 

The hpss_Rename function changes the name of the file or directory currently named by Old to New. 

Parameters 

Old Specifies the path name that currently names the file or directory. 

New Specifies the path name to which the name is to be changed. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POS1X. 1 rename. 


Search permission is denied on a component of the path prefix, or one of the 
directories containing Old or New denies write permission, or write permission is 
required and denied for a directory pointed to by the Old or New arguments. 

The Old or New parameter is a NULL pointer. 

The New argument points to a directory, and the Old argument points to a file 
that is not a directory. 

The file named by Old is a directory, and the link count of the parent directory of 
New already contains the maximum allowed number of links. 

ENAMETOOLONG The length of the Old or New argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Old or New argument points to an empty 

string. 

ENOTDIR A component of the path prefix is not a directory. 

ENOTEMPTY The path named by New is a directory containing entries other than dot and dot- 

dot. 


Error Conditions 

EACCES 

EFAULT 

EISDIR 

EMLINK 


See Also 
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hpssRenameHandle, hpssUnlink. 


Notes 


2.1.113. hpss_RenameHandle 

Purpose 

Rename a file or directory. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_RenameHandle( 


ns_Obj Handle_t 

*OldHandle, 

/* 

IN 

*/ 

char 

*OldPath, 

/* 

IN 

*/ 

ns_Obj Handle_t 

*NewHandle, 

/* 

IN 

*/ 

char 

*NewPath, 

/* 

IN 

*/ 

sec_cred_t 

*Ucred); 

/* 

IN 

*/ 


Description 

The hpss_RenameHandle function changes the name of the file or directory currently named by OldPath, 
taken relative to the directory indicated by OldHandle to the new name NewPath, taken relative to the 
directory indicated by NewHandle. 

Parameters 


OldHandle 

OldPath 

NewHandle 

NewPath 

Ucred 


Specifies the current parent object handle. 

Specifies the current path name relative to OldHandle. 

Specifies the new parent object handle. 

Specifies the new path name relative to NewHandle. 

User credentials. If NULL, the credentials in the current thread context are 
used. 


Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POS1X. 1 rename. 

Error Conditions 


EACCES Search permission is denied on a component of the path prefix, or one of the 

directories containing OldHandle or NewHandle denies write permission, or 
write permission is required and denied for a directory pointed to by the 
OldHandle or NewHandle arguments. 

EFAULT NewPath is a NULL pointer. 

E1NVAL The NewHandle or OldHandle parameter is NULL. 
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EISDIR The NewHandle argument points to a directory, and the OldHandle argument 

points to a file that is not a directory. 

EMLINK The file named by OldHandle is a directory, and the link count of the parent 

directory of NewHandle already contains the maximum allowed number of links. 

ENAMETOOLONG The length of OldPath or NewPath exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the OldPath or NewPath argument points to an 

empty string. 

ENOTD1R A component of the path prefix is not a directory. 

ENOTEMPTY The path named by NewPath is a directory containing entries other than dot and 

dot dot. 


See Also 


hpssRename, hpssUnlink. 

Notes 


None. 


2.1.114. hpss_ReopenBitfile 

Purpose 


Given the bitfile ID, reopen an HPSS file using the same file table entry. 


Synopsis 

#include "hpss_api.h" 
int 

hpss_ReopenBitfile( 
int 

hpssoid_t 

int 

sec_cred_t 

hps s_authz_token_t 


Fildes, /* IN */ 
*BitFileID, /* IN */ 
Oflag, /* IN */ 
*Ucred, /* IN */ 
*AuthzT±cket ); /* IN */ 


Description 

The hpss_ReopenBitfile routine reopens the bitfile specified by BitFilelD, using the file table entry 
currently associated with Fildes. 

Parameters 

Fildes Specifies the file handle for the currently open file. 

BitFilelD Points to the bitfile ID of the file to be reopened. 

Oflags Specifies the file status and file access modes to be assigned. Applicable values 

given below may be OR'ed together. Refer to POSIX. 1 for specific behavior. 
ORDONLY 

OWRONLY 
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ORDWR 


OAPPEND 

OTRUNC 

Ucred Points to client's user credentials. 

AuthzTicket Points to area where authorization ticket is to be returned. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EBADF Fildes does not refer to an open file. 

EBUSY The open file descriptor is in use by another thread. 

EFAULT The BitFilelD or AuthzTicket parameter is a NULL pointer. 

EINPROGRESS The file is currently being staged. The open should be retried at a later time. 

EINVAL Qflag does not contain a valid access mode or BitfilelD or AuthzTicket is NULL. 

ENOENT No entry exists for the specified bitfile ID. 

See Also 

hpss Open, hpss OpenBitfile. 

Notes 

If this routine fails, the file table entry identified by Fildes is not freed (it is marked as STALE), so that a 
subsequent effort can be made for this same file table entry. 

2.1.115. hpss_ResetSubSysStats 

Purpose 

Reset Storage Subsystem statistics. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_ResetSubSysStats( 

unsigned32 SubsystemID, /* IN */ 

subsys_stats_t *StatsOut ) ; /* OUT */ 

Description 

The hpss_ResetSubSysStats routine resets the stage, migration, purge, and delete counts in the Storage 
Subsystem and sets the last reset time to the current time. 

Parameters 

SubsystemID Subsystem identifier. 
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StatsOut 


Points to an area that will contain the current Storage Subsystem statistics 
values. 


Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EFAULT The StatsOut parameter is a NULL pointer. 

See Also 

hpssGetSubSysStats. 

Notes 


None. 

2.1.116. hpss_Rewinddir 

Purpose 

Reset position of an open directory stream. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Rewinddir( 

int Dirdes ); /* IN */ 


Description 

The hpss_Rewinddir function resets the position of an open directory stream corresponding to Dirdes to 
the beginning of that directory. 

Parameters 

Dirdes Specifies the open directory stream handle for which the position is to be reset. 

Return Values 

Upon successful completion, a value of zero is returned. If an error is encountered, a negative value is 
returned whose absolute value is described below. 

The specified directory descriptor does not correspond to an open directory or 
Dirdes is negative, or there are too many open file and directory descriptors. 

Another client thread is currently using this directory descriptor. 

Connection for this entry no longer valid. 

Readdir, hpss ReaddirHandle, hpss Closedir. 
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Error Conditions 


EBUSY 

ESTALE 


hpss Opendir, hpss 



Notes 


hpss_Rewinddir is altered from POSIX to return the values described above (whereas the POSIX 
rewinddir function does not return a value). Providing a failure indication was thought to be more 
important than strict POSIX compatibility. 

2.1.117. hpss_Rmdir 

Purpose 

Remove an HPSS directory. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Rmdir( 

char *Path ); /* IN */ 


Description 

The hpss_Rmdir function removes the directory named by Path. The directory will only be removed if the 
directory is empty. 

Parameters 

Path Specifies the path name of the directory to be removed. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX. 1 rmdir. 

Search permission is denied on a component of the path prefix, or write 
permission is denied on the parent directory of the directory to be removed. 

The named directory is currently in use and cannot be removed. 

The Path parameter is a NULL pointer. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 

ENOTEMPTY The named directory contains entries other than dot and dot-dot. 

See Also 

hpssRmdirHandle, hpssRmdirNoLookup, hpssMkdir, hpssUnlink. 

Notes 

None. 


Error Conditions 

EACCES 

EBUSY 

EFAULT 
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2.1.118. hpss_RmdirHandle 

Purpose 

Remove an HPSS directory. 

Synopsis 

#include "hpss_api.h 
int 

hpss_RmdirHandle( 

ns_Obj Handle_t 
char 

sec cred t 


*ObjHandle, /* IN */ 
*Path, /* IN */ 
*Ucred); /* IN */ 


Description 

The hpss_RmdirHandle function removes the directory named by Path taken relative to the directory 
referenced by ObjHandle. The directory will only be removed if the directory is empty. 

Parameters 

ObjHandle Parent directory object handle. 

Path Specifies the path name of the directory to be removed. 

Ucred User credentials. If NULL, the credentials in the current thread context are 

used. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX. 1 rmdir. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix, or write 

permission is denied on the parent directory of the directory to be removed. 

EBUSY The named directory is currently in use and cannot be removed. 

EFAULT The Path parameter is a NULL pointer. 

EINVAL ObjHandle is a NULL pointer. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 

component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 

ENOTEMPTY The named directory contains entries other than dot and dot-dot. 

See Also 

hpssRmdir, hpssRmdirNoLookup, hpssMkdir, hpssUnlink. 

Notes 

None. 
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2.1.119. hpss_RmdirNol_ookup 

Purpose 

Remove an HPSS directory. 

Synopsis 

#include "hpss_api.h 
int 

hpss_RmdirNoLookup( 
ns_Obj Handle_t 
char 

sec_cred_t 

Description 

The hpss_RmdirNoLookup function removes the directory named by Path taken relative to the directory 
referenced by ObjHandle. The directory will only be removed if the directory is empty. 

Parameters 

ObjHandle Parent directory object handle. 

Path Specifies the path name of the directory to be removed. 

Ucred User credentials. If NULL, the credentials in the current thread context are 

used. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX. 1 rmdir. 

Error Conditions 

Search permission is denied on a component of the path prefix, or write 
permission is denied on the parent directory of the directory to be removed. 

The named directory is currently in use and cannot be removed. 

The Path parameter is a NULL pointer. 

ObjHandle is a NULL pointer. 

The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

The named file does not exist, or the Path argument points to an empty string. 
A component of the Path prefix is not a directory. 

The named directory contains entries other than dot and dot-dot. 

See Also 

hpssRmdir, hpssRmdirHandle, hpssMkdir, hpssUnlink. 

Notes 

This function is different from other rmdir calls in that it doesn't make any extra path traverse or get 


EACCES 

EBUSY 

EFAULT 

EINVAL 

ENAMETOOLONG 

ENOENT 

ENOTDIR 

ENOTEMPTY 


* ObjHandle, /* IN */ 
*Path, /* IN */ 
* Ucred) ; /* IN */ 
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attribute calls before deleting the specified directory. 

2.1.120. hpss_SetACL 

Purpose 

Set the Access Control List of a file. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_SetACL( 

char *Path, /* IN */ 

unsigned32 Options, /* IN */ 

ns_ACLConfArray_t *ACL ) ; /* IN */ 


Description 

The hpss_SetACL function replaces the access control list for the file named by Path. 

Parameters 

Path Names the file for which the ACL is being replaced. 

Options Bit vector used to specify what type of ACL is to be retrieved. One of: 

HPSS ACL OBJECT ACL - return object's normal ACL 

HPSSACLINITIALOBJECTACL - return the initial-object ACL. 

(only valid for directory or fileset root objects) 

HPSS ACL INITIAL CONTAINER ACL - return the initial-container ACL. 
(only valid for directory or fileset root objects) 

ACL Points to the new access control list for the file. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below: 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix. 

EFAULT The Path or ACL parameter is a NULL pointer. 

One of the following has occurred: 

• More than one of the HPSS ACL OPTION * bits are set. 

EINVAL • ObjHandle is NULL. 

• HP S S ACL INITIAL C ONTAINERACL or 

HPSS ACL INITIAL OBJECT ACL was set and the ACL object is 
not a directory or fileset root. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 

component of the path name exceeds the system-imposed limit. 
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ENOENT 

ENOTDIR 

EPERM 


The named file does not exist, or the Path argument points to an empty string. 
A component of the Path prefix is not a directory. 

The client does not have the appropriate privileges to perform the operation. 


See Also 


hpssSetACLHandle, hpssDeleteACL, hpssDeleteACLHandle, hpssGetACL, 
hpssGetACLHandle, hpssUpdateACL, hpssUpdateACLHandle 

Notes 

Exactly one of the HPSS ACL OPTION * bits must be set in the Options bit vector. 


2.1.121. hpss_SetACLHandle 

Purpose 

Set the Access Control List of a file. 

Synopsis 

#include "hpss_api.h" 
int 

hpss SetACLHandle( 

*/ 
*/ 
*/ 
*/ 
*/ 


ns_ObjHandle_t *ObjHandle, /* IN 
char *Path, /* IN 
sec_cred_t *Ucred, /* IN 
unsigned32 Options, /* IN 
ns_ACLConfArray_t *ACL ); /* IN 


Description 

The hpss_SetACLHandle function sets the access control list for the file named by Path taken relative to 
the directory indicated by ObjHandle. 

Parameters 

ObjHandle Parent directory's object handle. 

Path Names the file for which the ACL is being replaced. 

Ucred User credentials. If NULL, the credentials in the current thread context are 

used. 

Options Bit vector used to specify what type of ACL is to be retrieved. One of: 

HPSS ACL OBJECT ACL - Return object’s normal ACL. 

HPSS ACL INITIAL OBJECT ACL - Return the initial-object ACL. (Only 
valid for directory or fileset root objects) 

HPSS A CL INITIAL CONTAINER A CL - Return the initial-container ACL. 
(Only valid for directory or fileset root objects) 

ACL Points to the new access control list for the file. 

Return Values 
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Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below: 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix. 

EFAULT The Path or ACL parameter is a NULL pointer. 

EINVAL One of the following has occurred: 

• More than one of the HPSSACLOPTION* bits are set. 

• ObjHandle is NULL. 

• HP S SACLINITIALC ONTAINER ACL or 

HPSS ACL INITIAL OBJECT ACL was set and the ACL object is 
not a directory or fileset root. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 

EPERM The client does not have the appropriate privileges to perform the operation. 

See Also 


hpssSetACL, hpssDeleteACL, hpssDeleteACLHandle, hpssGetACL, hpssGetACLHandle, 
hpssUpdateACL, hpssUpdateACLHandle 


Exactly one of the HPSS ACL OPTION * bits must be set in the Options bit vector. 

2.1.122. hpss_SetAcct 

Purpose 

Change the current account code. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_SetAcct( 

acct_rec_t NewCurAcct ); /* IN */ 


Description 

The hpss_SetAcct routine changes the accounting code used when creating files and directories for the 
current thread. 

Parameters 

NewCurAcct Specifies the value to be used for the account code for created files and 

directories. 


Return Values 
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Upon successful completion, hpss_SetAcct returns zero. Otherwise, a negative value is returned, the abso¬ 
lute value of which is equal to an ermo value defined below: 


Error Conditions 

EFAULT 


EINVAL 


ENOENT 

EPERM 


The account name with this account code is NULL. 

The client is configured for Unix-style accounting, and therefore the account 
code cannot be changed. 

Account doesn't exist. 

User is not a member of this account. 


See Also 


hpss AcctCodeToName, hpss AcctNameToCode , hpss Chacct, hpss ChacctByName, 
hpss GetAcct, hpss GetAcctName, hpss SetAcctByName 


None. 

2.1.123. hpss_SetAcctByName 

Purpose 

Change the current account name. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_SetAcctByName( 

char *NewAcctName ) /* IN */ 


Description 

The hpss_SetAcctByName routine changes the current session account name for the current site for this 
thread. Since each site contacted by each thread of the Client API will have its own session account, the 
account name returned is that of the site managing the current working directory. 

Parameters 

NewAcctName When using site-style accounting, this is the new session account name for the 

current site. However, when using UID accounting, NewAcctName can have 
one of several special meanings: 

"" - means set the current session account to the UID of the user 

String form of an account number (eg. "123") - means change the current 
session account index to 123. 

User name (eg."smithj") - means use the UID of user "smithj" as the new 
current session account index. 


Return Values 

Upon successful completion, hpss_SetAcctByName returns 0. Otherwise, hpss_SetAcctByName returns a 
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negative value, the absolute value of which indicates the specific error. 


Error Conditions 


EFAULT NewAcctName is a NULL pointer. 


ENAMETOOLONG 

ENOENT 

EPERM 


Length of string pointed to by NewAcctName greater than allowed. 
(HPSSMAXACCOUNTNAME - 1) 

The account specified by NewAcctName doesn't exist. 

The user does not have sufficient privilege to change the account name to 
NewAcctName, or NewAcctName is not defined at the site indicated by the 
client's current working directory. 


See Also 


hpss GetAcct, hpssChacct, hpss SetAcct, hpssGetAcctName, hpss ChacctByName. 


Notes 


If the user’s realm ID is foreign, then a message is returned advising that site-style accounting is required. 
If the NewAcctName is null, the the user’s uid will be returned. If the NewAcctName is a number, then the 
same number will be returned. Otherwise, the account name is looked up. If the entry is found, then the 
corresponding uid is returned. If the entry is not found, ENOENT is returned. 

2.1.124. hpss_SetAttrHandle 

Purpose 

Alter file attribute values. 

Synopsis 

#include "hpss_api.h 
int 

hpss_SetAttrHandle( 
ns_Obj Handle_t 
char 

sec_cred_t 
u_signed64 
hps s_vattr_t 
u_signed64 
hps s_vattr_t 

Description 

The hpss_SetAttrHandle function updates attribute values for the file or directory named by Path, taken 
relative to the directory indicated by ObjHandle. The attributes to be updated are indicated by SelFlagsIn, 
and the new attribute values are contained in the structure pointed to by Attrln. Indication of attributes 
actually changed are returned in SelFlagsOut, and the new attribute values in AttrOut. 

If the input Path refers to a symbolic link, hpss_SetAttrHandle returns information about the link itself. 
The hpss_FileSet* attributes functions operate on the object to which the link points. 

Parameters 


ObjHandle, 
*Path, 

*Ucred, 

SelFlagsIn, 

*Attrln, 
*SelFlagsOut, 
*AttrOut ) ; 


/* IN */ 
/* IN */ 


7 

IN */ 
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ObjHandle 

Path 

Ucred 

SelFlagsIn 


Attrln 

SelFlagsOut 

AttrOut 


Parent object handle. 

Points to the name of the file for which attribute values are to be changed. 

User credentials. If NULL, the credentials in the current thread context are 
used. 

Bitmask which indicates which attributes are to be set in the Core Server 
attributes. Refer to hpss_FileSetAttributes for a list of attributes that can be 
set using this function. 

Points to a structure containing the new attribute values. 

Bitmask indicating the attributes that were set. 

Points to a structure that will contain the file attribute values after completion 
of this request. 


Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which indicates the specific error. 

Error Conditions 


EACCES Search permission is denied for a component of the path prefix. 

EFAULT The Path, Attrln or AttrOut parameter is a NULL pointer. 

EINVAL An attribute value or selection flag is invalid, or the ObjHandle is NULL. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOSPC Resources could not be allocated to satisfy the request. 

ENOTDIR A component of the Path prefix is not a directory. 

EOPNOTSUPP The requested change is not supported. 

EPERM The client does not have the appropriate privileges to change the file's attributes. 


hpssFileGetAttributes, hpssFileGetAttributesHandle, hpssFileGetAttributesSOID, 
hpssFileSetAttributesHandle, hpssFileSetAttributesSOID, hpssChown, hpssChmod, hpssUtime. 

Notes 

None. 


2.1.125. hpss_SetAuditlnfo 

Purpose 

Set per-thread audit information. 
Synopsis 

#include "hpss_api.h" 
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int 

hpss_SetAuditInfo( 

unsigned int EndUserHostAddr) ; /* IN */ 


Description 

This routine sets up per-thread information that will appear in Core Server security audit messages. 

Parameters 

EndUserHostAddr IP address of end user's host. 

Return Values 

Upon successful completion, a value of zero is returned. 

Error Conditions 

None. 

See Also 

None. 


Notes 


This routine should be called by every thread that wants to use per-thread audit information. If the routine 
is never called, then the audit messages will show the host address of the server (eg., ftpd) that initiated the 
request. This is typically not very helpful; so the servers should call the routine at least once. If the routine 
is called once by one thread but not by another thread, then the audit messages will show the host address 
established by the first thread. This features lets ftpd call the routine once in the main thread rather than 
forcing ftpd to call it in every thread that contacts Core Server. 

2.1.126. hpss_SetConfiguration 

Purpose 

Update the current Client API configuration information. 

Synopsis 

#include "hpss_api.h" 

#include "api_internal.h" 
long 

hpss_SetConfiguration( 

api_config_t *ConfigIn ) ; /* IN */ 


Description 

The hpss_SetConfiguration routine updates the current configuration values for the Client API. 

Parameters 


Configln 

Points to a structure that contains the new configuration attributes value 
settings. 

Return Values 
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Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EFAULT The Configln parameter is a NULL pointer. 

EINVAL Invalid configuration attribute value setting. 


See Also 


hpss GetConfiguration, hpss ClientAPIReset. 

Notes 


None. 


2.1.127. hpss_SetCOSByHints 

Purpose 

Set Class Of Service of an open, empty file. 

Synopsis 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 


#include "hpss_api.h" 
int 

hpssjSetCOSByHints( 

int Filedes, 

unsigned32 Flags, 

hpss_cos_hints_t *H±ntsPtr, 

hpss_cosj?riorities_t *PrioPtr, 
hpss_cos_md_t *COSPtr ); 


Description 

The hpss_SetCOSByHints routine is used to attempt to place a file in an appropriate Class of Service 
before any data has been written to that file. This interface is primarily used when the file size is not known 
at the time the file is created, but based on the knowledge of the file at the time of the first write, a better 
Class of Service may be determined. 

Parameters 


Filedes 

Flags 


HintsPtr 

PrioPtr 

COSPtr 


Return Values 


Specifies the open file handle for which the Class of Service is to be set. 

Specifies flags which affect the processing of this request. Valid values are: 
BFS RESET SEGSIZE - Indicates that the request is only to set a new storage 
segment size. 

Points to a structure that provides attribute values for selection of a new Class 
of Service or storage segment size. 

Points to a structure that contains relative priorities for the attribute values 
indicated by the HintsPtr parameter. 

Points to a structure that will contain the attribute values for the selected Class 
of Service and storage segment size. 
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Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 


EBADF 

EBUSY 

EFAULT 

EINVAL 

EPERM 

ENOTDIR 

See Also 


The specified file descriptor does not refer to an open file. 

The file is currently in use by another client thread, or the Core Server could not 
complete the request at the current time. 

One of HinstPtr, PrioPtr, or COSPtr is a NULL pointer. 

The specified COS hints are invalid. 

The client does not have the appropriate privileges to perform the request. 

A component of the Path prefix is not a directory. 


hpssOpen, hpssOpenHandle, hpssOpenBitfile, hpssOpenBitfileVAttrs. 


Notes 


None. 


2.1.128. hpss_SetFileOffset 

Purpose 


Set the current file offset for an open file, given a 64-bit offset value. 


#include <unistd.h> 

#include "hpss_api.h" 
int 

hpss_SetFileOffset( 

int Fildes, 

u_signed64 Offsetln, 
int Whence, 

int Direction, 

u_signed64 *OffsetOut ); 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 


Description 

The hpss_SetFileOffset function sets the file offset for the open file handle, Fildes. Refer to the POSIX. 1 
Iseek function for more detailed information. Both input and output offset values are 64-bit values, to 
provide accessibility to the full range of FIPSS file sizes. Note that since the Offsetln value is unsigned, the 
Direction parameter is provided to specify whether Offsetln should be used to move forward or backward in 
the file. 

Parameters 

Fildes Specifies the open file handle for which the file offset is to be set. 

Offsetln Specifies the number of bytes to be used in calculating the new file offset - 

dependent on the value of Whence and Direction as to the final effect on the 
new file offset. 
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Whence 


Direction 


OffsetOut 

Return Values 


Specifies how to interpret the Ojfsetln parameter in setting the file pointer 
associated with the Fildes parameter. Values for the Whence parameter are as 
follows: 

SEEKSET - file offset set to Offsetln. 

SEEKCUR - file offset set to current offset plus Offsetln. 

SEEKEND - file offset set to current end of file plus Offsetln. 

SEEK CUR - file offset set to current offset plus Ojfsetln. 

SEEK END - file offset set to current end of file plus Offsetln. 

Specifies whether Offsetln should be used to move forward or backward in the 
file. 

HPSS SET OFFSET FORWARD - consider Offsetln as being a nonnegative 
number. 

HPSS SET OFFSET BACKWARD - consider Offsetln as being a negative 
number. 

Points to an area to contain the file offset as a result of processing this request. 


Upon successful completion, hpss_SetFileOffset returns zero. Otherwise hpss_SetFileOffset returns 
negative value, the absolute value of which indicates the specific error. 

Error Conditions 


EBADF The specified file descriptor does not refer to an open file. 

EBUSY The file is currently in use by another client thread. 

EFAULT OffsetOut is a NULL pointer. 

EINVAL The Whence or Direction parameter is invalid or the resulting offset would be 

invalid such as a negative value or beyond the largest supported file size. 

ENOSPC Resources could not be allocated to satisfy the request. 


See Also 


hpss Read, hpssWrite, hpss Lseek. 

Notes 


None. 

2.1.129. hpss_SetLoginCred 

Purpose 

Establish HPSS login credentials. 

Synopsis 

#include "hpss_api.h" 
signed32 

hpss_SetLoginCred( 
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char 

hp s s_au thn_mech_t 
hps s_rpc_cred_type_t 
hps s_rpc_au th_type_t 
void 


*Princ±palName, 
Mechanism, 
CredType, 
AuthType, 

*Authenticator) ; 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 


Description 

This routine is called to set an HPSS login credential. A newly set credential will be refreshed in the 
background and an hpss_PurgeLoginCred call must be issued to end update of the specified user 
credentials. 

Parameters 


PrincipalName 

Mechanism 

CredType 

AuthType 

Authenticator 


Specifies the server's principal name. 
Security mechanism. 

Type of credentials needed. 
Authenticator type. 

Pointer to the authenticator. 


Return Values 

Upon successful completion, a value of zero is returned. Otherwise, one of the error conditions below is 
returned. 

Error Conditions 


EINVAL PrincipalName is a NULL pointer or principle is invalid. 

See Also 

hpssPurgeLoginCred 

Notes 

None. 


2.1.130. hpss_SiteldToName 

Purpose 

Convert a given HPSS site id to its corresponding HPSS site name. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_SiteIdToName( 

hpss_uuid_t *SiteId, /* IN */ 

char *SiteName ); /* OUT */ 


Description 

The hpss_SiteIdToName routine converts the HPSS site id given in Siteld to its corresponding string 
representation, returned in SiteName. When an error is encountered, hpss_Site!dToName will return 
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immediately. 


Parameters 

Siteld 


SiteName 


If the site id pointer is NULL, or points to a zeroed parameter, the current local 
id is used. 

An HPSS site’s text name. If the site name is NULL, return the current local 
site name. Site name should be a string of at least HPSSMAXDESCNAME 
(32) bytes. 


Return Values 

Upon successful completion, a value of 0 is returned. Otherwise, a negative value is returned, the absolute 
value of which is equal to an ermo value defined below. 

Error Conditions 

ENOENT The value passed in Siteld does not correspond to a known HPSS site. 

ECONN There was a communication problem during the translation. 


See Also 


hpssSiteN ameT old 

Notes 


None. 


2.1.131. hpss_SiteNameTold 

Purpose 

Convert a given HPSS site name to its corresponding HPSS site id. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_SiteNameToId( 

char *SiteName, /* IN */ 

hpss_uuid_t *Siteld ); /* OUT */ 

Description 

The hpssSiteNameToId routine converts the HPSS site name given in SiteName to its corresponding HPSS 
site id, returned in Siteld. When an error is encountered, hpss SiteNameToId will return immediately. 

Parameters 


SiteName An HPSS site’s text name. If the site name pointer is null, or points to an 

empty string, the current local site name is used. 

Siteld A pointer to an HPSS site’s UUID. If the site id is null, return the current local 

site id. 

Return Values 
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Upon successful completion, a value of 0 is returned. Otherwise, a negative value is returned, the absolute 
value of which is equal to an ermo value defined below. 

Error Conditions 

ENOENT The value passed in SiteName does not correspond to a known HPSS site. 

ECONN There was a communication problem during the translation. 

See Also 


hpssSiteldToN ame 

Notes 


None. 


2.1.132. hpss_Stage 

Purpose 


Stage a piece of a file to a specified level in the storage hierarchy. 


Synopsis 

#include "hpss_api.h" 
int 

hpss_Stage( 
int 

u_signed64 

u_signed64 

unsigned32 

unsigned32 


Fildes, 

Offset, 

Length, 
StorageLevel, 
Flags ) ; 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 


Description 

The hpss_Stage routine stages part of an open file, specified by Fildes, Offset and Length to a level in the 
storage hierarchy, specified by StorageLevel. The Flags argument is used to control behavior of the 
request. 

Parameters 


Fildes 

Offset 

Length 

StorageLevel 

Flags 


Specifies the file descriptor, identifying the file to be staged. 

Specifies the offset of the start of the data to be staged. 

Specifies the length of the data to be staged. 

Identifies the level in the storage hierarchy to which the data is to be staged. 
Currently, the only supported value is 0. 

Controls the behavior of the stage request. Valid values include: 

BFS STAGE ALL - stage entire file. 

BFS ASYNCH CALL - return after initiating stage. 


Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
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absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EBADF The supplied file descriptor does not correspond to an open file. 

EINVAL The Flags, Offset or Length argument is invalid. 

EBUSY The specified file descriptor is currently in use. 

EPERM The client does not have the appropriate privileges to perform the operation. 

See Also 

hpssMigrate, hpssPurge, hpss StageCallBack. 

Notes 

None. 


2.1.133. hpss_StageCallBack 

Purpose 

Initiate staging a piece of a file in the background. 

Synopsis 

#include "hpss_api.h" 

int 

hpss_StageCallBack( 
char 

u_signed64 
u_signed64 
unsigned32 
bfs_callback_addr_t 
unsigned32 
hpss_reqid_t 
hpssoid_t 


*Path, 

Offset, 

Length, 
StorageLevel, 
* CallBackPtr, 
Flags, 

*ReqID, 
*BitfileID ); 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 
/* OUT */ 


Description 

The hpss_StageCallBack routine initiates a background stage of part of a file, specified by Fildes, Offset 
and Length to a level in the storage hierarchy, specified by StorageLevel. The Flags argument is used to 
control behavior of the request. 

Parameters 


Path 

Offset 

Length 

StorageLevel 

CallBackPtr 

Flags 


Specifies the pathname of the file to be staged. 

Specifies the offset of the start of the data to be staged. 

Specifies the amount of the data to be staged. 

Identifies the level in the storage hierarchy to which the data is to be staged. 
Callback information. If NULL, no callback actions are taken. 

Controls the behavior of the stage request. Valid values include: 

BFS STAGE ALL - stage entire file. 
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ReqlD Assigned request identification number. 

BitfilelD Bitfile ID. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EACCESS Search permission is denied for a component of the path prefix. 

EFAULT The Path parameter is a NULL pointer. 

EINVAL The value of the Offset parameter is beyond the end of the file or the 

StorageLevel parameter is invalid for the storage hierarchy. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 

component of the pathname exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 

See Also 

hpssMigrate, hpssPurge, hpssStage. 

Notes 

None. 

2.1.134. hpss_Stat 

Purpose 

Get file status (POSIX). 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Stat( 

char *Path, 

hpss_stat_t *Buf ) 

Description 

The hpss_Stat function obtains information about the file named by Path and returns it in the structure 
pointed to by Buf Refer to POSIX. 1 for more detailed information. If Path refers to a junction, the 
junction will be traversed. 

Parameters 

Path Points to the path name of the file being queried. 

Buf Points to a stat structure that will contain the status information for the file. 

Return Values 


/* IN */ 
/* OUT */ 
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Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX. 1 stat. 

Error Conditions 

Search permission is denied for a component of the path prefix. 

The Path or Buf parameter is a NULL pointer. 

The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

The named file does not exist, or the Path argument points to an empty string. 
A component of the Path prefix is not a directory. 

See Also 


EACCES 

EFAULT 

ENAMETOOLONG 

ENOENT 

ENOTDIR 


hpssChown, hpss Chmod, hpss Utime, hpssFileGetAttributes, hpssFileGetAttributesHandle, 
hpssFileGetAttributesSOID, hpssFileGetXAttributes, hpssFileSetAttributes, 
hpssFileSetAttributesHandle, hpssFileSetAttributesSOID, hpssLstat, hpssFstat, 
hpssGetListAttrs, hpssReadAttrs. 


Note that if the named file is a symbolic link, information is returned for the file to which the contents of the 
link point. See hpss_Lstat to obtain information about the symbolic link itself. 

2.1.135. hpss_Statfs 

Purpose 

Returns file system information for a Class of Service. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Statfs( 

unsigned32 COSId, /* IN */ 

hpss_statfs_t *StatfsBuffer ) ; /* OUT */ 


Description 

The hpss_Statfs routine returns file system information as defined in the statfs structure. 

Parameters 

COSId Specifies the identifier for the Class of Service that is being queried. 

StatfsBuffer Points to area to contain the file system information. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 
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EFAULT 

EINVAL 


The StatfsBujfer parameter is a NULL pointer. 
The specified Class of Service does not exist. 


See Also 


None. 


Notes 


1. The block size, fbsize, is that of the top storage class in the hierarchy. 

2. The fname field of the statfs structure will return the site name of the root Core Server. 

2.1.136. hpss_Statvfs 

Purpose 

Returns file system information for a Class of Service. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Statvfs( 

unsigned32 Cosld, /* IN */ 

hpss_statvfs_t *StatvfsBuffer ) ; /* OUT */ 


Description 

The hpss_Statvfs routine returns file system information as defined in the statvfs structure for the given 
Class of Service as a total from all Core Servers which manage files in the Class of Service. 

Parameters 

Cosld The identifier for the Class of Service that is being queried. 

StatvfsBuffer Pointer to area to contain the file system information. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EFAULT The StatvfsBuffer parameter is a NULL pointer. 

EINVAL The specified Class of Service does not exist. 

See Also 

None. 

Notes 

1. The block size, f bsize, is that of the top storage class in the hierarchy. 

2. The f_pack field of the statvfs structure will return the site name of the local Core Server that contains 
the most free space for the given Class of Service. 
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2.1.137. hpss_Symlink 

Purpose 

Create a symbolic link. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Symlink ( 

char *Contents, /* IN */ 

char *Path ); /* IN */ 

Description 

The hpss_Symlink routine creates a symbolic link pointing to the pathname specified in Contents with the 
link's name identified by Path. 

Parameters 

Contents Specifies the path name to which the symbolic link will point. 

Path Specifies the name of the symbolic link to be created. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix, or write 

permission is denied on the parent directory of the specified path name. 

EFAULT The Path or Contents parameter is a NULL pointer. 

EEXIST The specified link already exists. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT No entry exists for a component of the path name. 

ENOTDIR A component of the Path prefix is not a directory. 


See Also 


hpssReadlink, hpssReadlinkHandle, hpss SymlinkHandle. 

Notes 


None. 

2.1.138. hpss_SymlinkHandle 

Purpose 

Create a symbolic link. 
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Synopsis 

#include "hpss_api.h" 
int 

hpss_SymlinkHandle( 
ns_Obj Handle_t 
char 
char 

sec_cred_t 
hps s_vattr_t 


*ObjHandle, 
* Contents, 
*Path, 
*Ucred, 
*AttrsOut) ; 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 


Description 

The hpss_SymlinkHandle function creates a symbolic link with the name Path (taken relative to 
ObjHandle), with the contents specified by Contents. 

Parameters 

ObjHandle Object handle of existing file. 

Contents Specifies the path name to which the symbolic link will point. 

Path Specifies the name of the symbolic link to be created. 

Ucred User credentials. If NULL, the credentials in the current thread context are 

used. 

AttrsOut Returned attributes of new symbolic link. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix, or write 

permission is denied on the parent directory of the specified path name. 

EFAULT The Path or Contents parameter is a NULL pointer. 

EEXIST The specified link already exists. 

EINVAL ObjHandle is a NULL pointer. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT No entry exists for a component of the path name. 

ENOTDIR A component of the Path prefix is not a directory. 

See Also 

hpssReadlink, hpssReadlinkHandle, hpss Symlink. 

Notes 

None. 


HPSS Programmer's Reference July 2008 

Release 6.2 (Revision 2.0) 


164 



2.1.139. hpss_ThreadCleanUp 

Purpose 

Cleans up a thread's Client API state. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_ThreadCleanUp ( 

pthread_t ThreadID ); /* IN */ 


Description 

The hpss_ThreadCleanUp routine frees resources used by a thread's Client API context. 

Parameters 

ThreadID Specifies the thread identifier for the thread whose resources are to be freed. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

ENOENT State for the specified thread could not be found. 

See Also 

None. 


Notes 


The hpss_ThreadCleanUp routine should be called once for each thread which terminates and has 
previously called the Client API. 

2.1.140. hpss_Truncate 

Purpose 

Set the length of a file. 

Synopsis 

#include "hpss_api.h 
int 

hpss_Truncate( 
char 

u_signed64 

Description 

The hpss_Truncate routine sets the length of a file, specified by the Path argument. If the new file length 
is less than the current length, the space allocated beyond the new length will be freed. If the new length is 
greater than the current length, a hole is created in the file. 


*Path, /* IN */ 

Length ); /* IN */ 
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Parameters 

Path Specifies the path name of the file to be truncated. 

Length Specifies the new length of the file. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix, or write 

permission is denied on the file. 

EFAULT The Path parameter is a NULL pointer. 

EINVAL Path specifies a directory. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The specified path name does not exist. 

ENOTDIR A component of the Path prefix is not a directory. 

See Also 

hpssTruncateHandle, hpssFtruncate, hpss Fclear, hpssFileSetAttributes. 

Notes 


None. 

2.1.141. hpss_TruncateHandle 

Purpose 

Set the length of a file. 

Synopsis 

/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 


#include "hpss_api.h" 
int 

hpss_TruncateHandle( 
ns_Obj Handle_t 
char 

u_signed64 
sec cred t 


ObjHandle, 
*Path, 
Length, 
Ucred); 


Description 

The hpss_TruncateHandle function sets the file length for the file specified by ObjHandle. 

Parameters 

ObjHandle Object file handle. 

Path Specifies the path name of the file to be truncated. 
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Length Specifies the new length of the file. 

Ucred User credentials. If NULL, the credentials in the current thread context are 

used. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

Search permission is denied on a component of the path prefix, or write 
permission is denied on the file. 

The Path parameter is a NULL pointer. 

Path specifies a directory or ObjHandle is a NULL pointer. 

The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

The specified path name does not exist. 

A component of the Path prefix is not a directory. 

Ftruncate, hpssFclear, hpssFileSetAttributes. 


2.1.142. hpssJJmask 

Purpose 

Set the file creation mask. 

Synopsis 

#include "hpss_api.h" 

mode_t 

hpss_Umask( 

mode_t Cmask ); /* IN */ 

Description 

The hpss_Umask function sets the file mode creation mask of the thread and returns the previous value of 
the mask. Refer to POSIX.l umask for further details. 

Parameters 

Cmask Specifies the file mode creation mask to be used by subsequent 

hpss Open, hpss OpenHandle, hpss Create, hpss CreateHandle, 
hpss CreateDMHandle, hpss Mkdir, and hpss MkdirHandle calls. 

Return Values 


EACCES 

EFAULT 

EINVAL 

ENAMETOOLONG 

ENOENT 

ENOTDIR 

See Also 

hpss Truncate, hpss 

Notes 

None. 
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hpss_Umask returns the previous file mode creation mask for the thread. 

Error Conditions 

The hpss_Umask function is always successful and no return values are reserved to indicate an error. 

See Also 

hpssOpen, hpss OpenHandle, hpssCreate, hpss CreateHandle, hpss Mkdir, hpss MkdirHandle. 

Notes 

None. 

2.1.143. hpssJJnlink 

Purpose 

Remove an entry from an HPSS directory. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_Unlink( 

char *Path ); /* IN */ 

Description 

The hpss_Unlink function removes the entry named by the Path, and decrements the link count of the file. 
If the link count becomes zero, the file will be deleted when it is no longer open by any client. 

Parameters 

Path Names the directory entry to be removed. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX. 1 unlink. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix, or write 

permission is denied on the directory containing the link to be removed. 

EFAULT The Path parameter is a NULL pointer. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 

EPERM The file named by Path is a directory. 

See Also 

hpss Close, hpss_UnlinkHandle,hpss_Link, hpss LinkHandle. 
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Notes 


1 . Note that using hpss_Unlink to remove directory names is not supported. 

2. Also note that if the Path refers to a symbolic link, the link itself shall be removed. 

2.1.144. hpssJJnlinkHandle 

Purpose 

Remove an entry from an HPSS directory. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_UnlinkHandle( 

ns_ObjHandle_t *ObjHandle, /* IN */ 

char *Path, /* IN */ 

sec_cred_t *Ucred) ; /* IN */ 


Description 

The hpss_UnlinkHandle function removes the entry name by Path, taken relative to the directory indicated 
by ObjHandle, and decrements the link count for the file. If link count becomes zero, the file will be deleted 
when it is no longer open to any client. 

Parameters 

ObjHandle Parent object handle. 

Path Names the directory entry to be removed. 

Ucred User credentials. If NULL, the credentials in the current thread context are 

used. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX. 1 unlink. 

Search permission is denied on a component of the path prefix, or write 
permission is denied on the directory containing the link to be removed. 

The Path parameter is a NULL pointer. 

ObjHandle is a NULL pointer. 

The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

The named file does not exist, or the Path argument points to an empty string. 

A component of the Path prefix is not a directory. 

The file named by Path is a directory. 


Error Conditions 

EACCES 

EFAULT 

EINVAL 

ENAMETOOLONG 

ENOENT 
ENOTDIR 
EPERM 
See Also 
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hpssClose, hpssLink, hpssLinkHandle, hpssUnlink. 


Notes 


1 . Note that using hpss_Unlink to remove directory names is not supported. 

2. Also note that if the Path refers to a symbolic link, the link itself shall be removed. 

2.1.145. hpss_UnlinkNoLookup 

Purpose 

Remove an HPSS file. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_UnlinkNoLookup( 

ns_Obj Handle_t *ObjHandle, 

char *Path, 

sec_cred_t *Ucred ); 

Description 

The hpss_UnlinkNoLookup function removes the file named by Path taken relative to the directory 
referenced by ObjHandle. 

Parameters 

ObjHandle Parent directory object handle. 

Path Specifies the path name of the file to be removed. 

Ucred User credentials. If NULL, the credentials in the current thread context are 

used. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX. 1 unlink. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix, or write 

permission is denied on the parent directory of the file to be removed. 

EBUSY The named file is currently in use and cannot be removed. 

EFAULT The Path parameter is a NULL pointer. 

EINVAL ObjHandle is a NULL pointer. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 

component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 


/* IN */ 
/* IN */ 
/* IN */ 
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See Also 


hpssUnlink, hpssUnlinkHandle, hpssRmdir. 

Notes 


This function is different from other unlink calls in that it doesn't do any extra path traversals or get attribute 
calls before deleting the specified file. 

2.1.146. hpssJJpdateACL 

Purpose 

Update entries in the Access Control List of a file. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_UpdateACL( 

char *Path, 

unsigned32 Options, 

ns_ACLConfArray_t *ACL ); 


/* IN */ 
/* IN */ 
/* IN */ 


Description 

The hpss_UpdateACL function updates entries, specified by ACL, in the access control list for the file 
named by Path. 


Path Names the file for which the ACL is being updated. 

Options A bit vector containing bits which control the behavior of hpss_UpdateACL. 

It is possible to specify which ACL is to be updated, and to specify the behavior 
of hpss_UpdateACL while calculating the MASKOBJ. 

Options can be used to mimic the behavior of the following acl_edit options: 

-n, -c, and -p. This mimicking is done using the following mutually-exclusive 
constants: 

HPSSACLDONTCALCMASK 

Specifies that a new MASK OBJ should not be calculated. This option is 
useful when the ACL operations require the calculation of a new MASK OBJ, 
but doing so would result in an error. This option allows the operations to be 
carried out, but a new MASK OBJ is not calculated. 

HPSSACLCALCMASKIGNOREERRORS 

Creates or modifies the object's MASK OBJ entry with permissions equal to 
the union of all entries other than type USEROBJ, OTHER OBJ, and 
UNAUTHENTICATED. This creation or modification is done after all other 
modifications to the ACL are performed. The new MASK OBJ is set even if it 
grants permissions previously masked out. It is recommended that this option 
be used only if not specifying it results in an error. This option is useful only for 
objects that support the MASK OBJ entry type and are required to recalculate 
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a new MASKOBJ after they are modified. 
HPSSACLPURGEMASKEDPERMS 

Purges all masked permissions (before any other modifications are made). This 
option is useful only for ACLs that contain an entry of type MASK OBJ. Use it 
to prevent unintentionally granting permissions to an existing entry when a new 
MASK OBJ is calculated as a result of adding or modifying an ACL entry. 

Options can also be used to specify which ACL is to be updated. The following 
mutually-exclusive constants can be used to make this selection: 

HPSSACLOBJECTACL 

HPS SACLINITIALC ONT AINERACL 

HPSSACLINITIALOBJECTACL 

If an update operation creates a MASK OBJ that unintentionally adds 
permissions to an existing ACL entry, the modification causing the 
MASK OBJ recalculation will abort with an error unless the 
HPSS ACL CALC MASK IGNORE ERRORS or 
HPSS ACL DONT CALC MASK options are specified. 

ACL Points to the ACL entries to be updated. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 


Search permission is denied on a component of the path prefix. 

The Path or ACL parameter is a NULL pointer. 

There are two sets of mutually exclusive flags available through the Options 
parameter. Some invalid combination of flags was provided. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 

EPERM The client does not have the appropriate privileges to perform the operation. 


Error Conditions 


EACCES 

EFAULT 


See Also 


hpssUpdateACLHandle, hpss DeleteACL, hpss DeleteACLHandle, hpss GetACL, 
hpss GetACLHandle, hpss SetACL, hpss SetACLHandle. 


None. 
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2.1.147. hpssJJpdateACLHandle 

Purpose 

Update entries in the Access Control List of a file. 

Synopsis 

#include "hpss_api.h" 
int 

hpss_UpdateACLHandle( 

ns_ObjHandle_t *ObjHandle, /* IN */ 

char *Path, /* IN */ 

sec_cred_t *Ucred, /* IN */ 

unsigned32 Options, /* IN */ 

ns_ACLConfArray_t *ACL ); /* IN */ 


Description 

The hpss_UpdateACLHandle function updates entries, specified by ACL, in the access control list for the 
file named by Path taken relative to the directory indicated by ObjHandle. 


ObjHandle Parent object directory handle. 

Path Names the file for which the ACL is being updated. 

Ucred User credentials. If NULL, the credentials in the current thread context are 

used. 

Options A bit vector containing bits which control the behavior of hpss_UpdateACL. 

It is possible to specify which ACL is to be updated, and to specify the behavior 
of hpss_UpdateACLHandle while calculating the MASKOBJ. 

Options can be used to mimic the behavior of the following acl_edit options: 

-n, -c, and -p. This mimicking is done using the following mutually-exclusive 
constants: 

HPSSACLDONTCALCMASK 

Specifies that a new MASK OBJ should not be calculated. This option is 
useful when the ACL operations require the calculation of a new MASK OBJ, 
but doing so would result in an error. This option allows the operations to be 
carried out, but a new MASK OBJ is not calculated. 

HPSSACLCALCMASKIGNOREERRORS 

Creates or modifies the object's MASK OBJ entry with permissions equal to 
the union of all entries other than type USER OBJ, OTHER OBJ, and 
UNAUTHENTICATED. This creation or modification is done after all other 
modifications to the ACL are performed. The new MASK OBJ is set even if it 
grants permissions previously masked out. It is recommended that this option 
be used only if not specifying it results in an error. This option is useful only for 
objects that support the MASK OBJ entry type and are required to recalculate 
a new MASK OBJ after they are modified. 
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HPSS_ACL_PURGE_MASKED_PERMS 

Purges all masked permissions (before any other modifications are made). This 
option is useful only for ACLs that contain an entry of type MASKOBJ. Use it 
to prevent unintentionally granting permissions to an existing entry when a new 
MASK OBJ is calculated as a result of adding or modifying an ACL entry. 

Options can also be used to specify which ACL is to be updated. The following 
mutually-exclusive constants can be used to make this selection: 

HPSSACLOBJECTACL 

HPS SACLINITIALC ONT A1NERACL 

HPSSACLINITLALOBJECTACL 

If an update operation creates a MASKOBJ that unintentionally adds 
permissions to an existing ACL entry, the modification causing the MASK OBJ 
recalculation will abort with an error unless the 
HPSSA CL CALC MASK IGNORE ERRORS or 
HPSSA CL DONT CALC MASK options are specified. 

ACL Points to the ACL entries to be updated. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value defined below. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix. 

EFAULT The Path or ACL parameter is a NULL pointer. 

EINVAL There are two sets of mutually exclusive flags available through the Options 

parameter. Some invalid combination of flags was provided. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 
component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 

EPERM The client does not have the appropriate privileges to perform the operation. 


See Also 


hpssUpdateACL, hpssDeleteACL, hpssDeleteACLHandle, hpssGetACL, hpssGetACLHandle, 
hpssSetACL, hpssSetACLHandle. 


None. 

2.1.148. hpssJJtime 

Purpose 
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Set access and modification times of an HPSS file. 

Synopsis 

#include Cutime.h> 

#include "hpss_api.h" 
int 

hpss_Utime( 

char *Path, /* IN */ 

const struct utimbuf *Times); /* IN */ 


Description 

The hpss_Utime function sets the access and modification times of the file named by Path to the values 
specified in the structure pointed to by Times. Refer to POSIX. 1 for more detailed information. 

Parameters 

Path Names the file for which times are being changed. 

Times Points to a structure containing the new time values. 

Return Values 

Upon successful completion, a value of zero is returned. Otherwise, a negative value is returned, the 
absolute value of which is equal to an ermo value set by POSIX. 1 utime. 

Error Conditions 

EACCES Search permission is denied on a component of the path prefix. 

EFAULT The Path parameter is a NULL pointer. 

ENAMETOOLONG The length of the Path argument exceeds the system-imposed limit, or a 

component of the path name exceeds the system-imposed limit. 

ENOENT The named file does not exist, or the Path argument points to an empty string. 

ENOTDIR A component of the Path prefix is not a directory. 

EPERM The client does not have the appropriate privileges to perform the operation. 

See Also 

hpssStat, hpssStatfs, hpssStatvfs, hpss FileGetAttributes, hpss FileGetAttributesHandle, 
hpss FileSetAttributes, hpss FileSetAttributesHandle, hpssSetAttrHandle. 

Notes 

None. 

2.1.149. hpss_Write 

Purpose 

Write data from a client buffer to a contiguous section of an HPSS file, beginning at the current file offset. 

Synopsis 

#include "hpss_api.h" 
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Fildes, 
*Buf, 
Nbyte ); 


ssize_t 
hpss_Write( 
int 

const void 
size_t 


/* IN */ 
/* IN */ 
/* IN */ 


Description 

The hpss_Write function attempts to write Nbyte bytes from the client buffer pointed to by Buf to the file 
associated with the open file handle, Fildes. 

Parameters 


Fildes Specifies the open file handle associated with the file to which data is to be 

written. 

Buf Points to a buffer where the data is to be found. 

Nbyte Specifies the number of bytes to be written. 

Return Values 

Upon successful completion, hpss_Write returns a nonnegative value that is the number of bytes written. 
Otherwise, hpss_Write returns a negative value; the absolute value of which is equal to an ermo value set 
by POSIX.l write. 

Error Conditions 

EBADF The specified file descriptor does not correspond to a file opened for writing. 

EBUSY The file is currently in use by another client thread. 

EFAULT The Buf parameter is out of range. 

EFBIG The write operation would cause the file to exceed the system-imposed 

maximum file length. 

EIO An input/output or HPSS internal error occurred. 

ENOSPC There is no free space remaining to satisfy the write request. 


See Also 


hpss Open, hpss OpenHandle, hpss OpenBitflle, hpss Read, hpss Lseek, hpss SetFileOffset, 
hpss ReadList, hpss WriteList. 


Notes 

None. 

2.2. Data Definitions 

This section describes key internal data definitions and all externally used data definitions which are provided by this 
subsystem. A data definition may be represented by constructs such as data structures and constants. For each data 
definition, a description, format (including parameter descriptions), and clients which access the data definition are 
provided. Note: Descriptions of the IOD and IOR structures may be found in Chapter 3. 
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2.2.1. Account Record - acct_rec_t 

Description 

The account record contains the HPSS account identifier number. 


Format 


The API configuration structure has the following format: 

typedef unsigned32 acct_rec_t; 

2.2.2. API Configuration Structure - api_config_t 

Description 

The API configuration structure contains values that control optional features of the Client API 
configuration. 


Format 


The API configuration structure has the following format: 


typedef struct api_config { 
long 
long 
long 
long 
int 
int 
int 
int 
long 
long 
long 
long 
int 

hp s s_authn_me ch_t 

hp s s_rp c_j? r o t_l eve l_t 

char 

char 

char 

} api_config_t; 


Flags; 

DebugValue; 

TransferType; 

NumRetries; 

BusyDelay; 

BusyRetries; 

TotalDelay; 

LimitedRetries; 

MaxConnections; 
ReuseDataConnections; 
UsePortRange; 

RetryStagelnp; 

DMAPWriteUpdates; 

AuthnMech; 

RPCProtLevel; 

DescName[HPSS_MAX_DESC_NAME]; 
DebugPath[HPSS_MAX_PATH_NAME]; 
HostName[HPSS_MAX_HOST_NAME]; 


Flaes 

Contains a bitmap of configuration flags. Valid values include: 


APIENABLELOGGING 


If logging compiled into Client API library, perform HPSS logging 
on errors. 


API USE CONFIG Use configuration from API. 

API DISABLE CROSS REALM If set, this flag prevents the Client API from contacting any servers 
outside of the local realm. Once set, this flag cannot be unset. This 
flag is set automatically when FTP logs in without security. 
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APIDISABLEJUNCTIONS If set, this flag prevents the Client API from processing any requests 

which require it to traverse a junction. Once set, this flag cannot be 
unset. NFS will always set this flag explicitly. 


Debui’Value 

If zero, indicates that Client API will not send debug messages to an output file; otherwise messages will be 
sent (note that all debug messages are conditionally compiled into the library). 

TransferTvpe 

Indicates what data transfer mechanism is to be used for transfers handled by the Client API. 
APITRANSFERTCP Use TCP/IP. 

APITRANSFERIPI3 Use IPO protocol if support compiled in. 

API TRANSFER MVRSELECT Let mover select transfer protocol. 

NumRetries 

Used to control the number of retries to attempt when an operation fails. Currently this class of operation 
includes library initialization and communication failures. A value of zero indicates that no retries are to be 
performed and a value of negative one indicates that operation will be retried until successful. 

BusyDelay 

Used to control the number of seconds to delay between retry attempts. 

BusvRetries 

Used to control the number of retries to be performed when a request fails because the Core Server does not 
currently have an available thread to handle that request. A value of zero indicates that no retries are to be 
performed. A value of negative one indicates that retries should be attempted until either the request 
succeeds of fails for another reason. 

TotalDelav 

Used to control the number of total seconds to continue retrying a request. 

LimitedRetries 

Used to control the number of retry attempts for limited retry type errors. 

MaxConnections 

Maximum number of connections for use by the HPSS connection management service. 

ReuseConnections 

Used to control whether TCP/IP connections are to be left as long as a file is opened or closed after each 
read or write request. A non-zero value will cause connections to remain open, while a zero will cause 
connections to be closed. 

UsePortRanee 

Used to control whether the HPSS Mover(s) should use the configured port range when making TCP/IP 
connections for read and write requests. A non-zero value will cause the Mover(s) to use the port range. A 
value of zero will cause the Mover(s) to allow the operating system to select the port number. 

Retr y Sta g eln p 
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Used to control whether retries are attempted on opens of files in a Class of Service that is configured for 
background staging on open. A non-zero value indicates that open which would return -EINPROGRESS to 
indicate the file is being staged will be retried. A value of zero indicates that the -EINPROGRESS return 
code will be returned to the client. 

DMAPWriteUpdates 

Controls the frequency of cache invalidates that are issued to the XDSM file system. 

AuthnMech 

Authentication Mechanism to use (Unix or Keberos). 

RPCProtLevel 

Level of RPC protection to use. 

DescName 

Name to use when generating HPSS log messages. 


If generation of debug messages is enabled, the pathname of the file to which log messages will be directed. 
Special cases are "stdout" and "stderr". 

HostName 

Specifies the interface name to use for TCP/IP communications. 

2.2.3. API Distributed File Information - api_dist_fiIe_info_t 

Description 

The API Distributed File Information structure contains required information defining a distributed file. 


Format 


The api dist file info t structure has the following format: 


typedef struct { 

struct file_info { 

hpss_object_handle_t 

hpss_uuid_t 

u_signed64 

int 

unsigned32 
api_dmap_attrs_t 
} Info; 

uchar CkSum; 

} api_dist_file_info_t; 


bitfile_handle; 
CoreServerUUID; 
Offset; 

OpenFlag; 
FilesetCOS; 
DMattrs; 


bit file handle 

The HPSS bitfile object handle. 
CoreServerUUID 

The HPSS server universal identifier. 
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Offset 

Offset of the file from the beginning (bytes). 

OpenFlag 

Specifies the file status and file access modes to be assigned. Applicable values given below may be OR'ed 
together. Refer to POSIX. 1 for specific behavior. 


ORDONLY 

OWRONLY 

ORDWR 

OAPPEND 

OCREAT 

OEXCL 

OTRUNC 

Files etCOS 

The Class of Service assigned to the file. 

DMAttrs 

The DMAP attributes of the file. See the api dmap attrs t structure. 

CkSum 

The computed checksum for the file. 

2.2.4. API DMAP Attributes - api_dmap_attrs_t 

Description 

The API DMAP Attributes structure maintains related information concerning a distributed file. 

Format 


This structure has the following format: 


typedef struct { 
u_signed64 
unsigned32 
hpss_uuid_t 
unsigned32 
byte 

} api dmap attrs t; 


FilesetID; 

FilesetType; 

DMGuuid; 

HandleLength; 

Handle[HPSS_MAX_DMEPI_HANDLE_SIZE]; 


FilesetID 

The identifier for the DMAP fileset for the file. 


FilesetType 
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The following fileset types are defined: 

N S_FS_TYPE_B ACKEDUP 
N SFSTYPENATIVE 
NS_FS_TYPE_MIRRORED 
NSFSTYPENSLOCAL 
DMGuuid 

The DM Gateway universal identifier. 

HandleLeneth 

Length in bytes of the DMAP file handle. Maximum currently set at 32 bytes. 

Handle 

DMAP fde handle. 

2.2.5. API Name Specification - api_namespec_t 

Description 

The API Name Specification structure is used for converting HPSS realm and principal ids to/from their 
associated names. The API Name specification structure contains the translation type along with the 
principal and realm information that is to be converted. 


The apinamespect has the following format: 


typedef struct api_namespec { 


name spe c_type_t 

unsigned32 

unsigned32 

char 

char 

} api_namespec_t; 


Type ; 

Id; 

Realmld; 

Name[HPSS_MAX_PRINCIPLE_NAME]; 
RealmName[HPSS_MAX_REALM_NAME]; 


T .VPe 

The type of translation that is requested. The valid values are: 


NAMESPECREALM 

NAMESPECUSER 

NAMESPECGROUP 

NAMESPECSKIP 

Id 

The uid or gid of the principal. 
Realmld 


Translate realm name only. 

Translate user name and realm name. 
Translate group name and realm name. 
Do not translate this entry 
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The HPSS realm ID where the principal resides. 

Name 

The name of the principal. 

RealmName 

The name of the realm where the principal resides. 

2.2.6. Bitfile Volatile and Metadata Attributes - bf_attrib_t 

Description 

The attributes structure for the bitfile object contains all the volatile and metadata bitfile attributes. These 
are parameters relating to a bitfile. 


The bitfile attributes structure has the following format: 

struct bf_attrib { 

u_signed64 CurrentPosition; 

signed32 OpenCount; 

unsigned32 Familyld; 

bf_attrib_md_t BfAttribMd; 

} ; 

typedef struct bf_attrib bf_attrib; 
typedef bf_attrib bf_attrib_t; 

CurrentPosition 

Specifies the current byte position in the bitfile. 

OpenCount 

Specifies the current number of clients that have the bitfile open. 

Fantilvld 

Specifies the family identifier for the bitfile. 

BfAttribMd 

Specifies the structure of bitfile metadata attributes that are stored in the data base. 

2.2.7. Bitfile Volatile and Metadata Extended Attributes - bf_xattrib_t 

Description 

The attributes structure for the bitfile object contains all the volatile and metadata bitfile extended 
attributes. These are parameters relating to a bitfile and location of valid data. 


Format 


The bitfile extended attributes structure has the following format: 

struct bf_xattrib { 

u_signed64 CurrentPosition; 
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signed32 OpenCount; 

unsigned32 Familyld; 

bf_s c_attrib_t SCAttrib[HPSS_MAX_STORAGE_LEVELS] ; 
bf_attrib_md_t BfAttribMd; 

} ; 

typedef struct bf_xattrib bf_xattrib; 
typedef bf_xattrib bf_xattrib_t; 

CurrentPosition 

Specifies the current byte position in the bitfile. 

OpenCount 

Specifies the current number of clients that have the bitfile open. 

Familyld 

Specifies the family identifier for the bitfile. 

SCAttrib 

Specifies the storage class attributes at each valid level in the hierarchy. 

BfAttribMd 

Specifies the structure of bitfile metadata attributes that are stored in the data base. 

2.2.8. Bitfile Metadata Attributes - bf_attrib_md_t 

Description 

This structure contains the bitfile attributes metadata. These are parameters relating to a bitfile. 

LinkCount is always 1 for a existing bitfile in current HPSS release. On one bfs_Bitfile(Open)SetAttrs call, 
reverse maps (OwnerRec) can be either added or deleted. Both cannot be accomplished on the same call. 


Format 


The bitfile attributes metadata structure has the following format: 


struct bf_attrib_md { 
u_signed64 
signed32 
signed32 
signed32 
times tamp_sec_t 
times tamp_s e c_t 
time s tamp_se c_t 
times tamp_sec_t 
unsigned32 
unsigned32 
acct_rec_t 
unsigned32 
unsigned32 
u_signed64 
unsigned32 


DataLen; 
ReadCount; 
WriteCount; 
LinkCount; 
CreateTime; 
ModifyTime; 
WriteTime; 
ReadTime; 

COSId; 

NewCOSId; 

Acct ; 

Flags; 

StorageSegMult; 
RegisterBitmap; 
Realmld; 


} ; 
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typedef struct bf_attrib_md bf_attrib_md; 
typedef bf_attrib_md bf_attrib_md_t; 

DataLen 

Specifies the number of bytes of actual data that the bitfile contains. 

ReadCount 

Specifies the count of the number of times that all or part of the bitfile has been read. 

WriteCount 

Specifies the count of the number of times that data has been written to the bitfile. 

LinkCount 

Specifies the number of links to this bitfile. 

CreateTime 

Specifies the date and time the bitfile was created. 

ModifvTime 

Specifies the date and time the bitfile was last modified. 

WriteTime 

Specifies the date and time when data was last written to the bitfile. 

ReadTime 

Specifies the date and time when the bitfile was last read. 

COSId 

Specifies the class of service type (unsigned32) and indicates which of several classes of service the bitfile 
is in. This ID references a class of service record that defines the parameters for this particular class of 
service. When changing a file’s COS, this field is used by the hpss FileSetAttributes function. 

NewCOSId 

Indicates the new class of service that a file is to be changed to when the client changes the class of service 
on a bitfile. When the change has been completed, the value of this field is moved into COSId and this 
field is cleared. This field is read only. Use the COSId field to change a file’s COS. 

Acct 

Specifies the accounting metadata for the bitfile. It includes information needed to charge for data storage, 
access, transfers, quotas, etc. 

Flags 

Used to maintain boolean data related to the bitfile. The following constants correspond to flag bits: 
SYNCFILESETDATA Make consistency check 

HPSS DATA VALID HPSS data is valid 

CACHE DATA VALID File system cache is valid 
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BFSACCTSTATSVALID1 
BFS_ACCT_STATS_VALID2 
BFSNOPURGE 


Accounting stats are valid, bit 1 
Accounting stats are valid, bit 2 
Bitfile cannot be pmged 


Storag eSe gMult 

Storage segment multiple used to adjust size of disk storage segments. 

RegisterBitmap 

This bit vector is used to indicate which fields in the attribute structure the SSM wants to receive 
notifications about when the field changes. The following constants can be used to set the bits to indicate 
which fields are to be monitored: 

BFSREGOPENCOUNT 

BFSREGDATALEN 

BFS_REG_READ_COUNT 

BFS_REG_WRITE_COUNT 

BFS_REG_LINK_COUNT 

BFSREGCREATETIME 

BFS_REG_MODIFY_TIME 

BFS REG WRITE TIME 

BFSREGREADTIME 

BFS REG COS ID 

BFSREGACCT 

BFSREGREALMID 

BFSREGFAMILYID 

Realmld 

The client realm identifier. 

2.2.9. Bitfile Service Storage Class Attributes - bf_sc_attrib_t 

Description 

This structure contains storage class information for a specific storage hierarchy level at which the specified 
bitfile exists. 


Format 


The storage class attributes have the following format: 


struct bf_sc_attrib { 
bf_w_attrib_t 
unsigned32 
u_signed64 
unsigned32 
unsigned32 


WAttrib [ BFS_MAX_W_TO_RETURN_AT_LEVEL ] ; 
NumberOfWs ; 

BytesAtLevel; 

OptimumAccessSize; 

StripeWidth; 
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u_signed64 StripeLength; 

unsigned32 Flags; 

} ; 

typedef struct bf_sc_attrib bf_sc_attrib; 
typedef bf_sc_attrib bf_sc_attrib_t; 


VVAttrib 

An array of virtual volumes on which bitfile segments are contained. 
NumberOfWs 

Specifies the number of virtual volume entries in the array. 
BytesAtLevel 

Specifies the amount of data that exist at this level (in bytes). 
OptimumAccessSize 

Specifies the optimum access size of the storage class. 

StripeWidth 

Specifies the stripe width of the storage class. 

StripeLength 

Specifies the stripe length of the storage class. 

Flues 

The flags that defined the state of the fileset. Valid values include: 


BFSBFATTRSLEVELISDISK 

BFSBFATTRSLEVELISTAPE 

BFSBFATTRSDATAEXISTSATLEVEL 

BFSBFATTRSADDITIONALVVEXIST 


This is a disk storage level. 

This is a tape storage level. 

This is a tape storage level. 

More VVs exist than the maximum the structure can 
hold. 


2.2.10. Bitfile Service Virtual Volume Attributes - bf_w_attrib_t 

Description 

This structure contains Core Server virtual volume attributes for a specific storage level in the hierarchy. 


Format 


The bitfile virtual volume attributes have the following format: 


struct bf_w_attrib 
hpssoid_t 
signed32 
u_signed64 
pv_list_t 


WID; 

RelPosition; 
BytesOnW; 
*PVList; 
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} ; 

typedef struct bf_w_attrib bf_w_attrib; 
typedef bf_w_attrib bf_w_attrib_t ; 

VVID 

Specifies the virtual volume identifier. 

RelPosition 

Specifies the relative start position of first bitfile segment on this virtual volume. 

BvtesOn VV 

Specifies the number of bytes of the given file stored on this VV from the current contiguous set of bitfile 
segments. It is possible for BytesOnVV to be less than the total number of bytes of the given file that reside 
on this W if non- adjacent bitfile segments are stored on the same W. For example, if a file consists of 
three 1MB bitfile segments, with the first and third on VV ‘A’ and the second on W ‘B’, an 
hpss_FileGetXAttributes() call will return a list of three VVs (bf vv attrib t types), each with BytesOnVV 
= 1MB. On the other hand, if a file consists of three 1MB bitfile segments, with the first and second on VV 
‘A’ and the third on W ‘B’ an hpss_FileGetXAttributes() call will return a list of two VVs, the first with 
BytesOnVV = 2MB and the second with BytesOnVV = 1MB. 


A conformant array of physical volume attributes. 

2.2.11. Bitfile Callback Address - bfs_callback_addr_t 

Description 

The Bitfile Callback Address structure contains the host information, port number and an identification 
number which facilitates call backs during a stage process. 


Format 


The bfs callback addr t has the following format: 

struct bfs_callback_addr { 

unsigned32 addr; 

unsignedl6 port; 

unsignedl6 family; 

signed32 id; 

} ; 

typedef struct bfs_callback_addr bfs_callback_addr; 
typedef bfs_callback_addr bfs_callback_addr_t; 


Host address in network byte order. 
port 

Port number. 
family 
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Address family. 


Id 


Id to be returned during a callback. 


2.2.12. Core Server Attribute Structure - hpss_Attrs_t 

Description 


The Core Server external attribute structure contains fields for the various attributes (metadata) that the 

Core Server maintains for an objec 

t. 

Format 


The Core Server external attributes structure has the following format: 

struct hpss_Attrs { 


acct_rec_t 

Account; 

hpssoid_t 

Bitfileld; 

unsigned32 

Realmld; 

char 

Comment[256] ; 

unsigned32 

CompositePerms; 

unsigned32 

COSId; 

u_signed64 

DataLength; 

unsigned32 

DMDataStateFlags; 

byte 

DMHandle[HPSS_MAX_DMEPI_HANDLE_SIZE]; 

unsigned32 

DMHandleLength; 

unsigned32 

DontPurge; 

unsigned32 

EntryCount; 

unsigned32 

ExtendedACLs; 

unsigned32 

Familyld; 

ns_Obj Handle_t 

FilesetHandle; 

u_signed64 

Filesetld; 

u_signed64 

FilesetRootld; 

unsigned32 

FilesetStateFlags; 

unsigned32 

FilesetType; 

hpss_uuid_t 

GatewayUUID; 

unsigned32 

GID; 

unsigned32 

GroupPerms; 

unsigned32 

LinkCount; 

unsigned32 

MACSecLabel; 

unsigned32 

OpenCount; 

unsigned32 

OtherPerms; 

unsigned32 

ReadCount; 

u_signed64 

RegisterBitMap ; 

unsigned32 

SetGIDBit; 

unsigned32 

SetStickyBit; 

unsigned32 

SetUIDBit; 

unsigned32 

SubSystemld; 

times tamp_se c_t 

TimeCreated; 

time s tamp_s e c_t 

TimeLastRead; 

times tamp_se c_t 

TimeLastWritten; 

time s tamp_s e c_t 

TimeModified; 

unsigned32 

Type; 
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unsigned32 

unsigned32 

unsigned32 


UID; 

UserPerms; 
WriteCount; 


} ; 

typedef struct hpss_Attrs hpss_Attrs; 
typedef hpss_Attrs hpss_Attrs_t; 

Account 

Specifies opaque accounting information. 

BitFileld 

Specifies the bitfile identifier. 

Realmld 

Specifies the Realm identifier. 

Comment 

Specifies the uninterpreted client supplied ASCII text. 

CompositePerms 

Specifies the permission to an object after all ACLs have been examined and applied. 

COSId 

Specifies the class of service ID. 

DataLength 

Specifies the byte length of Data. 

DMDataState Flues 

A collection of three bits which describe the state of data which is stored in HPSS and simultaneously 
stored in some other filesystem such as XFS. The three bits which describe this state are: 

COREDMSTATECACHEDATAVALID 

COREDMSTATEHPSSDATAVALID 

COREDMSTATESYNCFILESETDATA 

DMHandle 

Specifies a handle that points back to a DMAP managed object. This field is opaque data to the Core 
Server. 

DMHandleLength 

Specifies the byte length of DMHandle. 

DontPuree 

A flag indicating whether a file can be purged. If 1, the file cannot be purged. 

Entr yCount 

Specifies a read-only field which contains the number of entries contained in a directory. If the object is not 
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a directory, the value is not defined. 
Extended A CLs 


A flag that indicates whether an object has extended ACLs (ACL entries other than userobj, groupobj, 
and otherobj). If 1, the object has extended ACLs. 

Familvld 

Identifies the fileset family identifier. 

FilesetHandle 

Specifies a Core Server object handle used to point to the root node of a fileset. 

Filesetld 

Specifies the fileset identifier that uniquely identifies the fileset an object belongs to. 

FilesetRootld 

Specifies a root ID of this fileset. 

FilesetStateFlaes 

Contains flag bits indicating the state of the fileset. The following constants define the possible states: 


CORE_FS_STATE_READ 

COREFSSTATEWRITE 

COREFSSTATEDESTROYED 

COREFSSTATEREADWRITE 

COREFSSTATECOMBINED 


Read is permitted. 

Write is permitted. 

The fileset has been destroyed. Neither reading nor writing will 
be permitted 

A combination of READ and WRITE. 

A combination of all bit settings above. 


FilesetTvpe 

Specifies the type of the fileset the attributes are for. This is a read-only field. The following constants 
define the fileset types: 


COREF ST YPEHP S SONL Y 
CORE FS TYPE ARCHIVED 
COREFSTYPENATIVE 
COREFSTYPEMIRRORED 
GID 


This fileset is an HPSS-only fileset. 

This fileset is a backup copy of some other fileset. 

This fileset is native to some other file system such as XFS. 
This fileset is a mirrored copy of some other fileset. 


Specifies the principal group identifier. 

GroupPenns 

Specifies the permissions granted to group members. 
LinkCount 

Specifies the number of hard links to a file object. 
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MACSecLabel 
A security label for the object. 

OpenCount 

Specifies the number of opens to a file object. 

OtherPerms 

Specifies the permissions granted to ‘other’ clients. 

ReadCount 

Specifies the number of times that all or part of the bitfile has been read. 

ResisterBitMap 

A bit vector used to indicate which fields in the attribute structure should trigger SSM notifications when 
changed. 

SetGIDBit 
For file objects: 

0 = do not set GID to owner. 

1 = set GID to owner. 

SetSticky Bit 
For file objects: 

0 = do not set the sticky bit. 

1 = set the sticky bit. 

SetUIDBit 
For file objects: 

0 = do not set UID to owner. 

1= set UID to owner. 

SubSvstemld 

Specifies the Subsystem ID. 

TimeCreated 

Specifies the time the object was created. 

TimeLastRead 

Specifies the last time the object was accessed. 

TimeLastWritten 

Specifies the last time the object was written. 

TimeModified 
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Specifies the time the object was modified. 

IXM 

This field is not settable. Specifies the ‘type’ of the object: 


NS_OBJECT_TYPE_DIRECTORY directory 

NSOBJECTTYPEFILE file 

NSOBJECTTYPEJUNCTION junction 

NS OBJECT TYPE SYM LINK symbolic link 

NS OBJECT TYPE HARD LINK hard link 

UID 


Specifies the User Identifier of the object’s owner. 

UserPerms 

Specifies the permissions granted to the owner of the object. 

WriteCount 

Specifies the number of writes to a file object. 

2.2.13. Name Service Object Attribute Bits - hpss_AttrBits_t 

Description 

Bits specifying the Name Service object attributes to retrieve or set. 

Format 

The hpss AttrBits t has the following format: 

typedef u_signed64 hpss_AttrBits_t; 

2.2.14. Authentication Mechanism Type - hpss_authn_mech_t 

Description 

This structure defines the different types of authentication mechanisms for HPSS. 

Format 

The hpssauthnmecht structure has the following format: 

enum hpss_authn_mech_t { 

hpss_authn_mech_invalid = 0, 
hpss_authn_mech_krb5 = 1, 
hpss_authn_mech_unix = 2, 
hpss_authn_mech_gsi = 3, 
hpss_authn_mech_spkm = 4 

} ; 

typedef enum hpss_authn_mech_t hpss_authn_mech_t; 


HPSS Programmer's Reference July 2008 

Release 6.2 (Revision 2.0) 


192 



2.2.15. Authentication Token Type - hpss_authz_token_t 

Description 

This structure defines the different types of HPSS authentication types. 

Format 

The hpss authz token t structure has the following format: 

struct hpss_authz_token { 
byte Version; 
unsigned32 DataLength; 
byte Data[HPSS_AUTHZ_TOKEN_DATA_SZ]; 
unsigned32 Timestamp; 
unsignedl6 SourceAddType; 
unsigned32 SourceAddrLength; 
byte SourceAddr[16]; 
unsigned32 CheckSumLength; 
byte Checksum[HPSS_AUTHZ_TOKEN_CKSUM_SZ]; 

} ; 

typedef struct hpss_authz_token hpss_authz_token; 

typedef hpss_authz_token hpss_authz_token_t; 

Version 

The version number of the authentication token, currently at version 1. 

DataLength 

Length of token data in bytes. Maximum length is currently set at 128 bytes; 

Data 

The token data. 

Timestamp 

A timestamp obtained using the system time() subroutine. The time() subroutine returns the number of 

seconds since the Epoch (00:00:00 GMT, January 1, 1970). 

SourceAddType 

Type of the source address. 

SourceAddrLength 

Length of the source address. 

SourceAddr 

The source address. 

CheckSumLength 

Length in bytes of Checksum. Maximum length is currently set at 64 bytes. 

Checksum 
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Checksum of the token data. 


2.2.16. File Creation Hint Structure - hpss_cos_hints_t 

Description 

The file creation hint structure contains information that allows clients to specify preferences or knowledge 
of file structure or access patterns that may affect operations of HPSS. 


Format 


The COS hints has the following format: 


struct hpss_cos_hints { 


unsigned32 

COSId; 

char 

COSName[HPSS_MAX_OBJECT_NAME] 

unsigned32 

Flags; 

u_signed64 

OptimumAccessSize; 

u_signed64 

MinFileSize; 

u_signed64 

MaxFileSize; 

unsigned32 

AccessFrequency; 

unsigned32 

TransferRate; 

unsigned32 

AvgLatency; 

unsigned32 

WriteOps; 

unsigned32 

ReadOps; 

unsigned32 

StageCode; 

unsigned32 

StripeWidth; 

u_signed64 

} ■ 

StripeLength; 

typedef struct hpss_cos 

: hints hpss cos hints; 

typedef hpss_cos_hints 

hpss_cos_hints_t; 

COSId 



The class of service that the bitfile belongs to. 

COSName 

Specifies the name of the class of service for this bitfile. 

Flans 

Flags used in bitfile creation, values are: 

HINTS FORCE MAX SEGSZ - Force maximum segment size for the bitfile. 
OptimumAccessSize 

Specifies the block size in bytes for this class of service that yields the maximum data transfer rate. 
MinFileSize 

Specifies the minimum size in bytes of a bitfile in this class of service. 

MaxFileSize 

Specifies the maximum size in bytes to which the bitfile can grow and remain in this class of service. 
AccessFrequencv 
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Specifies the expected rate of access for the bitfile. 

FREQHOURLY 

FREQDAILY 

FREQWEEKLY 

FREQMONTHLY 

FREQARCHIVE 

TransferRate 

Specifies the approximate file transfer rate in kilobytes per second. 

A va Latency 

Specifies the time in seconds from when a request is received by a Core Server until data actually begins to 
transmit. This is typically non-zero for tape media. 

WriteOps 

Specifies the valid write operations for the bitfile: 


FIPSS OP WRITE Allow write operations. 

FIPSS OP APPEND Allow append operations. 


ReadOps 

Specifies the valid read operations for the bitfile: 
FIPSS OP READ Allow read operations. 

StageCode 

Specifies the staging behavior desired: 
COSSTAGENOSTAGE 

COSSTAGEONOPEN 

COSSTAGEONOPENASYNC 

COSSTAGEONOPENBACKGROUND 
Stripe Width 

Specifies the stripe width of the class of service. 
StripeLength 

Specifies the stripe length of the class of service. 


File is not to be staged on open. The data will be read 
from the current level in the hierarchy, or data may 
be explicitly staged by the client. 

Entire file is to be staged to the top level in the 
hierarchy before open returns. 

Entire file is to be staged to the top level in the 
hierarchy without blocking in open. Reads / writes 
are blocked only until the portion of the file being 
accessed is staged. 

File is to be staged in a background task. 
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2.2.17. Class of Service Priorities - hpss_cos_priorities_t 

Description 

The class of service priorities structure assists a client in selecting a COS for a bitfile. Structure use - 
dynamic memory tables. 


Format 


The COS priorities has the following format: 

struct hpss_cos_priorities { 

unsigned32 COSIdPriority; 
unsigned32 COSNamePriority; 
unsigned32 OptimumAccessSizePriority; 
unsigned32 MinFileSizePriority; 
unsigned32 MaxFileSizePriority; 
unsigned32 AccessFrequencyPriority; 
unsigned32 TransferRatePriority; 
unsigned32 AvgLatencyPriority; 
unsigned32 WriteOpsPriority; 
unsigned32 ReadOpsPriority; 
unsigned32 StageCodePriority; 
unsigned32 StripeWidthPriority; 
unsigned32 StripeLengthPriority; 

} ; 

typedef struct hpss_cosj?riorities hpss_cosj?riorities; 

typedef hpss_cosj?riorities hpss_cosj?riorities_t; 

Valid priority values are: 

N OPRIORIT Y 

LOWESTPRIORITY 

LOW_PRIORITY 

DESIREDPRIORITY 

HIGHLYDESIREDPRIORITY 

REQUIREDPRIORITY 


COSIdPriority 

Specifies the class of service ID priority for the class of service the bitfile should be in. 
COSNamePriority 

Specifies the class of service name priority for this bitfile. 

OptimumAccessSizePriority 

Specifies the priority for the block size for this class of service that yields the maximum data transfer rate. 
MinFileSizePriority 

Specifies the priority for the minimum size in bytes of a bitfile in this class of service. 
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MaxFileSizePrioritv 

Specifies the priority for the maximum size in bytes to which the bitfile can grow and remain in this class of 
service. 

AccessFrequencvPriority 

Specifies the priority for the expected rate of access for the bitfile. 

TransferRatePrioritv 

Specifies the priority for the class of service file transfer rate. 

AvgLatencyPriority 

Specifies the class of service priority for the average latency time from request time until data begins to 
transfer. 

WriteOpsPrioritv 

Specifies the priority for the valid write operations for the bitfile. 

ReadOpsPrioritv 

Specifies the priority for the valid read operations for the bitfile. 

S tageCodePrioritv 

Specifies the priority for the desired stage code. 

Stripe WidthPrioritv 

Specifies the stripe width priority of the storage class. 

StripeLengthPriority 

Specifies the stripe length priority of the storage class. 

2.2.18. Class of Service Metadata Structure - hpss_cos_md_t 

Description 

The Class of Service metadata structure contains information about the configuration of a Class of Service. 

Format 


The Class of Service metadata structure has the following format: 


struct hpss_cos_md 
unsigned32 
unsigned32 
char 

unsigned32 

unsigned32 

u_signed64 

u_signed64 

unsigned32 

unsigned32 

unsigned32 

unsigned32 


{ 

COSId; 

Hierld; 

COSName[HPSS_MAX_OBJECT_NAME]; 
OptimumAccessSize; 

Flags; 

MinFileSize; 

MaxFileSize; 

AccessFrequency; 

TransferRate; 

AvgLatency; 

WriteOps; 
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unsigned32 ReadOps; 
unsigned32 StageCode; 

} ; 

typedef struct hpss_cos_md hpss_cos_md; 

typedef hpss_cos_md hpss_cos_md_t; 

COSId 

The class of service type. It indicates which of several classes of service the bitfile is in. 

Hierld 

The storage hierarchy associated with this Class of Service. 

COSName 

Specifies the name of the class of service for this bitfile. 

OptimumAccessSize 

Specifies the block size in bytes for this class of service that yields the maximum data transfer rate. 

Flans 

Optionally specify one of the following options: 

COSENFORCEMAXFILESIZE If ON, bitfiles cannot be created in this COS with a size 

greater than MaxFileSize. Attempts to do so will result in the 
request being rejected with an error. 

COSFORCESELECTION If ON, a client must explicitly select this COS in order to have 

a file assigned to it. If the client merely supplies general COS 
hints for a bitfile, this COS will not be selected. 

COS AUTO STAGE RETRY If ON, HPSS will automatically retry a failed stage from the 

primary copy if a valid secondary copy exists. 


MinFileSize 

Specifies the minimum size in bytes of a bitfile in this class of service. 

MaxFileSiz e 

Specifies the maximum size in bytes to which the bitfile can grow and remain in this class of service. 
AccessFrequencv 

Specifies the expected rate of access for the bitfile. 

FREQHOURLY 

FREQDAILY 

FREQWEEKLY 

FREQM ONTHLY 

FREQARCHTVE 

TransferRate 
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Specifies the approximate file transfer rate in kilobytes per second. 

A v<j Latency 

Specifies the time in seconds from when a request is received by a Core Server until data actually begins to 
transmit. This is typically non-zero for tape media. 

WriteOps 

Specifies the valid write operations for the bitfile: 


HPSS OP WRITE Allow write operations. 
HPSS OP APPEND Allow append operations. 


ReadOps 

Specifies the valid read operations for the bitfile: 
HPSS OP READ Allow read operations. 


Specifies the staging behavior desired: 


COS_STAGE_NO_STAGE 

COSSTAGEONOPEN 

COSSTAGEONOPENASYNC 

COSSTAGEONOPENBACKGROUND 


File is not to be staged on open. The data will be read 
from the current level in the hierarchy, or data may be 
explicitly staged by the client. 

Entire file is to be staged to the top level in the hierarchy 
before open returns. 

Entire file is to be staged to the top level in the hierarchy 
without blocking in open. Reads/writes are blocked only 
until the portion of the file being accessed is staged. 

File is to be staged as a background task. 


2.2.19. HPSS Directory Entry - hpss_dirent_t 

Description 

The HPSS directory entry structure contains the directory’s name and a handle to the Core Server for this 
directory. In addition, it contains the offset of the next directory entry. 

Format 


typedef struct hpss_dirent { 

u_signed64 d_offset; 

ns_ObjHandle_t d_handle; 
unsignedl6 d_reclen; 

unsignedl6 d_namelen; 

char d_name[HPSS_MAX_FILE_NAME]; 

} hpss_dirent_t; 

d offset 

The offset of the next directory entry. 
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d handle 

The handle to the Core Server for the directory. 
d recle n 

The record length of the directory. 
d namelen 

The number of characters in the directory name. 
d name 

The name of the directory. 

2.2.20. Extended Transaction Outcome - hpss_ExTrans_Outcome_t 

Description 

Indicates the outcome of an extended transaction. 

Format 

This data type is declared as follows: 

typedef unsigned32 hpss_ExTransOutcome_t; 

2.2.21. File Attribute Structure - hpss_fileattr_t 

Description 

The file attribute structure contains file attributes that are managed by the Core Server. 

Format 

The file attribute structure has the following format: 

typedef struct hpss_fileattr { 

ns_ObjHandle_t ObjectHandle; 

hps s_Attrs_t Attrs; 

} hpss_fileattr_t; 

O bjectHandle 

Specifies the handle that refers to the open file or directory. 

Attrs 

Specifies the file attributes managed by the Core Server. 

2.2.22. File Attributes Bit Data Type - hpss_fileattrbits_t 

Description 

This data type specifies the HPSS File Attributes Bits. 

Format 

This data type is declared as follows: 
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typedef u_signed64 hpss_AttrBits_t; 
typedef hpss_AttrBits_t hpss_fileattrbits_t; 

2.2.23. Extended File Attribute Structure - hpss_xfileattr_t 

Description 

The file attribute structure contains file attributes that are managed by the Core Server. This structure allows 
the user to retrieve the extended attributes. 


Format 


The file attribute structure has the following format: 

struct hpss_xfileattr { 

ns_ObjHandle_t ObjectHandle; 
hpss_ Attrs_t Attrs; 

bf_sc_attrib_t SCAttrib[HPSS_MAX_STORAGE_LEVELS]; 

} ; 

typedef struct hpss_xfileattr hpss_xfileattr; 
typedef hpss_xfileattr hpss_xfileattr_t; 


ObiectHandle 

Specifies the handle that refers to the open file or directory. 

Attrs 

Specifies the file attributes. 

SCAttrib 

Specifies the storage class attributes for each valid level in the hierarchy. 

2.2.24. Global Fileset Entry Structure - hpss_global_fsent_t 

Description 

The global fileset entry structure contains global fileset information. 

Format 


The global fileset entry structure has the following format: 


typedef struct { 

u_signed64 
unsigned char 
uuid_t 
uuid_t 

} hpss_global_fsent_t; 


Filesetld; 

FilesetName[HPSS_MAX_FS_NAME] 
GatewayUUID; 

CoreServerUUID; 


Filesetld 

The unique fileset identifier. 
FilesetName 
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The unique name of the fileset. 

GatewavUUID 

The identifier of the DMAP gateway that manages the fileset. 
CoreServerUUID 

The identifier of the Core Server that manages the fileset. 

2.2.25. Parallel I/O Callback Type - hpss_pio_cb_t 

Description 

This HPSS data type declares a callback function. 

Format 


The format for this data type is: 

typedef int (*hpssj>io_cb_t) ( 

void *, /* IN - Call back argument */ 

u_signed64, /* IN - Local file offset */ 

unsigned int *, /* IN/OUT - Length of requested data */ 

void **); /* IN/OUT - Pointer to first byte of data */ 

2.2.26. Parallel I/O Gap Information Type - hpss_pio_gapinfo_t 

Description 

The hpss_pio_gapinfo_t data type provides the required information determining a gap in the data. 


Format 


The format for this data type is: 

typedef struct hpssj?io_gapinfo_s { 
u_signed64 Offset; 

u_signed64 Length; 

} hpss_pio_gapinfo_t ; 


Offset 

Starting offset of the gap in bytes. 

Length 

Length of the data gap in bytes. 

2.2.27. Parallel Stripe Group Type - hpss_pio_grp_t 

Description 

This data type is a pointer to a parallel I/O stripe group. 

Format 

The format of this data type is: 
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typedef void *hpssj?io_grp_t; 

2.2.28. HPSS Parallel I/O Operation Type - hpss_pio_operation_t 

Description 

This data type defines the parallel I/O operations. 

Format 

The format of this data type is: 

typedef enum { HPSS_PIO_READ, HPSS_PIO_WRITE } hpss_pio_operation_t; 

2.2.29. HPSS Parallel I/O Parameters - hpss_pio_params_t; 

Description 

This data structure defines the parallel I/O parameters. 

Format 


The format of the hpss_pio_params_t data structure is: 

typedef struct hpssj?io_params_s { 
hpssjpio_operation_t Operation; 
unsigned32 ClntStripeWidth; 

unsigned32 BlockSize; 

unsigned32 FileStripeWidth; 

unsigned32 IOTimeOutSecs; 

hpss_pio_transport_t Transport; 
hpss_pio_options_t Options; 

} hpssj?io_params_t; 


Operation 

Specifies the type of operation. Valid values are: 

HPSSPIOREAD 
HP S SPIOWRITE 
ClntStripe Width 

Number of data elements in the client stripe. 

BlockSize 

Number of bytes in each data element in the data stripe. 

FileStripeWidth 

Number of data elements in the file stripe. 

IOTimeOutSecs 

Number of seconds to wait for I/O. Zero will get the default of 30 minutes. 
Transport 
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Type of data transport. Valid values are: 

HPSSPIOTCPIP 

Options 

Parallel I/O transport options. Valid values are: 

HP S SPIOPU SH 

HP S SPIOH ANDLEG AP 

2.2.30. HPSS Parallel I/O Transport Type - hpss_pio_transport_t 

Description 

This data type defines the types of parallel I/O transport types available. 

Format 

The format of this data type is: 

typedef enum { HPSS_PIO_TCPIP } hpssj?io_transport_t; 

2.2.31. HPSS I/O Request ID Type - hpss_reqid_t 

Description 

The hpss reqid t data type defines a unique HPSS I/O request identifier. 

Format 

The format for this data type is: 

typedef unsigned32 hpss_reqid_t; 

2.2.32. HPSS RPC Protection Level Type - hpss_rpc_prot_level_t 

Description 

This data type defines the level of protection to be used for the TO transaction. 

Format 


The format of this data type is: 

enum hpss_rpc_prot_level_t { 

hpss_rpc_j?rotect_connect = 1, 
hpss_rpc_protect_j?kt = 2, 
hpss_rpc_j?rotect_j?kt_integ = 3, 
hpss_rpc_j?rotect_j?kt_j?rivacy = 4 

} ; 

typedef enum hpss_rpc_prot_level_t hpss_rpc_prot_level_t; 

2.2.33. HPSS File Statistics Data Structure - hpss_stat_t 

Description 

This structure contains the variables specifying the file statistics. 
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Format 


The format of the hpssstatt structure is: 

typedef struct hpss_stat { 
unsigned32 st_dev; 

u_signed64 st_ino; 

unsignedl6 st_nlink; 

unsignedl6 st_flag; 

unsigned32 st_uid; 

unsigned32 st_gid; 

unsigned32 st_rdev; 

u_signed64 st_ssize; 

timestamp_sec_t hpss_st_atime; 
signed32 st_atime_n; 

timestamp_sec_t hpss_st_mtime; 
signed32 st_mtime_n; 

timestamp_sec_t hpss_st_ctime; 
signed32 st_ctime_n; 

unsigned32 st_blksize; 

unsigned32 st_blocks; 

signed32 st_vfstype; 

unsigned32 st_vfs; 

unsigned32 st_type; 

unsigned32 st_gen; 

u_signed64 st_size; 

unsigned32 st_mode; 

} hpss_stat_t; 

st dev 

Identifier of the device containing a directory entry for an HPSS file. 
st ino 

File serial number. 
st nlink 

Number of links to the file. 
stflag 
Flag word. 
st uid 

User ID of the file's owner. 
st_gid 

Group ID of the file's group. 
st rdev 

Identifier of a character or block special file only. 
st ssize 
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64 bit file size. 


hpss st atime 

Time of last access. 

st atime n 

Not used. 

hpss st mtime 

Time of last modification. 

st mtime n 

Not used. 

hpss st dime 

Time of last file status change. 
st ctime n 
Not used. 
st blksize 

Optimal blocksize for file system I/O operations. 
st blocks 

Actual number of blocks allocated. 
st vfstvpe 

Type of virtual file system. Not used. 
sl_vfs 

VFS number. Not used. 
st type 

Vnode type. Not used. 
st sen 

Inode generation number. Not used. 
st size 

64 bit file size. 
st mode 

File mode. Valid POSIX values for this are: 

S IFMT Mask used to determine file type. 

SIFREG Regular fde 

SIFDIR Directory 
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SJFBLK 

S_IFCHR 

SIFIFO 

SISUID 

SISGID 

SIRWXU 

SIRUSR 

SIWUSR 

SIXUSR 

SIRWXG 

SIRGRP 

SIWGRP 

SIXGRP 

SIRWXO 

SJROTH 

SIWOTH 

SIXOTH 


Block special file. 

Character special file. 

First in first out. 

Set user id on execution. 

Set group id on execution. 

Read, write, execute permissions for owner. 
Read permission for owner. 

Write permission for owner. 

Execute, search permission for owner. 

Read, write, execute permissions for group. 
Read permission for group. 

Write permission for group. 

Execute, search permissions for group. 
Read, write, execute permissions for others. 
Read permission for others. 

Write permission for others. 

Execute, search permissions for others. 


2.2.34. HPSS VFS File Statistics Structure - hpss_statvfs_t 

Description 

This data structure contains the HPSS vfs file statistics. 


Format 


The hpssstatvfst structure's format is: 

typedef struct hpss_statvfs { 
unsigned32 fjbsize; 
unsigned32 fjblocks; 
unsigned32 fjbfree; 
unsigned32 fjbavail; 
unsigned32 f_files; 
unsigned32 f_ffree; 
unsigned32 f_fsid; 
unsigned32 f_namemax; 

char f_fs tr[STATVFS_NAME_LENGTH] ; 

char f_fpack[STATVFS_NAME_LENGTH]; 

} hpss_statvfs_t; 


f bsize 

Preferred file system block size. 
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f blocks 

Total data blocks in file system. 
f bfree 

Number of free blocks in file system. 
f bavail 

Number of free blocks available to non-superuser. 

JUUes 

Total number of file nodes (inode in JFS). 
f ffree 

Number of free file nodes in file system. 

fjsid 

The file system's identifier. 
f namemax 

The maximum filename length. 

LslL 

A file system specific string. 
f pack 

File system pack name. 

2.2.35. HPSS Name Space Attributes Structure - hpss_vattr_t 

Description 

This structure contains the attributes of an HPSS name space object. 

Format 


The format for this structure is: 

typedef struct hpss_vattr { 
hpss_type_t 
hpss_mode_t 
hpss_uid_t 
hpss_gid_t 
unsigned32 
unsigned32 
unsigned32 
unsigned32 
unsigned32 
unsigned32 
unsigned32 
u_signed64 
u_signed64 


va_type; 
va_mode; 
va_uid; 
va_gid; 
va_fsid; 
va_serialno; 
va_nlink; 
va_rdev; 
va_nid; 
va_chan; 
va_aclsize; 
va_size; 
va_j?ref iosize ; 
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u_signed64 
u_signed64 
u_signed64 
time s tamp_sec_t 
time s tamp_s e c_t 
time s tamp_sec_t 
unsigned char 
unsigned32 
ns_Obj Handle_t 
hpssoid_t 
cos_t 

acct_rec_t 
} hps s_vattr_t; 

va type 

HPSS object type. 
va mode 

Unix permissions of object. 
va uid 

Unix id of object owner. 


va_blocksize; 
va_numblocks; 
va_ftid; 
va_atime; 
va_mtime; 
va_ctime; 
*va_acl; 
va_realm; 
va_objhandle; 
va_soid; 
va_cos ; 
va_account; 


Unix group id of object owner. 

vafsid 

Not used. 

va serialno 

Not used. 

va nlink 

Number of links to this object. 
va rdev 
Not used. 
va nid 

Network id for this object. 
va chan 

Channel for object device. 
va aclsize 
ACL size in bytes. 
va size 

HPSS object size in bytes. 
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va prefiosize 
Preferred I/O size. 
va blocksize 


HPSS object block size. 

va numblocks 

HPSS object block count. 

va ftid 

Fileset id. 

va atime 

Time of last access. 
va mtime 

Last modification time. 
va ctime 

Time of last status change. 
va acl 

Pointer to Access Control List. 

va realm 

Security realm id. 

va obihandle 

Name Server object handle. 

va soid 

HPSS bitfile identifier. 
va cos 

HPSS class of service identifier. 
vaacct 

HPSS account index. 

2.2.36. HPSS UUID Type - hpss_uuid_t 

Description 

This structure defines an HPSS UUID. 

Format 

The structure's format is: 

struct hpss_uuid { 
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unsigned32 time_low; 
unsignedl6 time_mid; 
unsignedl6 time_hi_and_version; 
unsigned8 clock_seq_hi_and_reserved; 
unsigned8 clock_seq^_low; 
byte node[6]; 

} ; 

typedef struct hpss_uuid hpss_uuid; 

typedef hpss_uuid hpss_uuid_t; 

2.2.37. HPSS Namespec Type - namespec_type_t 

Description 

This data type defines the types of namespace translation. 


Format 


The format for this data type is: 

typedef enum { 
NAMESPECJSKIP, 

NAME S PE C_REALM, 
NAMESPEC_USER, 
NAMESPEC_GROUP 
} name spe c_type_t; 


2.2.38. Name Service ACL Conformant Array - ns_ACLConfArray_t 

Description 

The nsACLConfArrayt structure describes a template for a conformant array of Name Service ACL 
entries. 


Format 


The nsACLConfArrayt structure has the following format: 

typedef struct { 

signed32 Length; 
ns_ACLEntry_t ACLEntry[*]; 

} ns_ACLConfArray_t; 


Specifies the number of ACL entries in the array. 


ACLEntry 

The array of ACL entries. 


2.2.39. Name Service Access Control List Entry - ns_ACLEntry_t 

Description 

The ns ACLEntry t structure describes a Name Service ACL entry. Each entry contains information such 
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as the type of entry (i.e., for a group or individual user), the identity and location of the user or group and 
the permissions that are allowed. 


Format 


The ns ACLEntry t structure has the following format: 


struct ns_ACLEntry { 
u_char 
u_char 
unsigned32 
unsigned32 


EntryType; 
Perms; 
Entryld; 
Realmld; 


typedef struct ns_ACLEntry ns_ACLEntry; 
typedef ns_ACLEntry ns_ACLEntry_t; 


EntrvTvpe 

Identifies the type of this ACL entry. These correspond to the following ACL tag types: userobj, 

userobjdelegate, user, user delegate, foreign user, foreign user delegate, group obj, 

group obj delegate, group, group delegate, foreign group, foreign group delegate, otherobj, 

other obj delegate, foreign other, foreign other delegate, any other, any other delegate, mask obj, or 

unauthenticated. 

Perms 

Specifies the permissions or access rights. 


Entrvld 

Depending on the EntryType, it can specify an identifier (usually a UID or GID). 

Realmld 

Specifies the realm identifier. 

2.2.40. Name Service Directory Entry - ns_DirEntry_t 

Description 

The Name Service directory entry structure defines the contents of an HPSS directory entry. 


Format 


The Name Service directory entry structure has the following format: 

struct DirEntryTag { 

char Name[HPSS_MAX_FILE_NAME]; 

ns_ObjHandle_t ObjHandle; 

u_signed64 ObjOffset; 

hps s_Attrs_t Attrs; 

} ; 

typedef struct DirEntryTag DirEntryTag; 
typedef DirEntryTag ns_DirEntry_t; 

Name 

Specifies the name of the directory entry. 
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ObiHandle 

Specifies the Name Service object handle of the directory entry. 

O bjOf fset 

Specifies the offset of the entry within the directory. 

Attrs 

Specifies attributes of the directory entry. 

2.2.41. Name Service Fileset Attributes Structure - ns_FilesetAttrs_t 

Description 

The Name Service fileset attribute structure contains fields for the various attributes (metadata) that the 
Core Server maintains for a fileset. 


Format 


The Name Server fileset attributes structure has the following format: 


struct ns_FilesetAttrs 
u_signed64 
u_signed64 
unsigned32 
unsigned32 
ns_Obj Handle_t 
u_signed64 
char 

unsigned32 

hpss_uuid_t 

unsigned32 

unsigned32 

byte 

u_signed64 

u_signed64 

u_signed64 

u_signed64 

u_signed64 


{ 

RegisterBitMap; 

ChangedRegisterBitMap; 

ClassOfService; 

FamilyId; 

FilesetHandle; 

Filesetld; 

FilesetName[HPSS_MAX_FS_NAME_LENGTH]; 
FilesetType; 

GatewayUUID; 

StateFlags; 

SubSystemld; 

UserData[NS_FS_MAX_USER_DATA]; 
DirectoryCount; 

FileCount; 

HardLinkCount; 

JunctionCount; 

SymLinkCount; 


} ; 

typedef struct ns_FilesetAttrs ns_FilesetAttrs; 
typedef ns_FilesetAttrs ns_FilesetAttrs_t; 


Re gisterBitMap 

A bit vector where each bit corresponds to a field in the record. 
ChangedRegisterBitMap 

A bit vector where each bit corresponds to a changed field in the record. 
ClassOfService 

The COS service configured for this fileset. 

Familvld 
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The fileset family identifier. This id is opaque to the Core Server. 

FilesetHandle 

A Core Server object handle which points to the root node of the fileset. 

Filesetld 

The unique identifier of this fileset. 

FilesetName 

The unique human readable fileset name. 

FilesetType 

Specifies the type of the fileset the attributes are for. This is a read-only field. The following constants 
define the fileset types: 

COREFST YPEHPSS ONLY This fileset is an HPSS-only fileset. 

CORE FS TYPE ARCFIIVED This fileset is a backup copy of some other fileset. 

CORE FS TYPE MIRRORED This fileset is a mirrored copy of some other fileset such as an 

XFS fileset. 


GatewayUUID 

The identifier of the gateway that processes DMAP requests for the fileset. 
StateFlags 

The flags that defined the state of the fileset. Valid values include: 


CORE FS STATE READ The fileset allows reads. 

COREFSSTATEWRITE The fileset allows writes. 

CORE FS STATE READ WRITE The fileset allows reads and writes. 

CORE FS STATE DESTROYED The fileset allows no access. 

SubSvstemld 

The HPSS storage subsystem that this name space object belongs to. 

UserData 

Uninterpreted data supplied by the client. This data can be ASCII, binary, or both. 
DirectoryCount 

The current number of directories in the fileset. 

FileCount 

The current number of files in the fileset. 

HardLinkCount 

The current number of hard links in the fileset. 

JunctionCount 
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The current number of junctions in the fileset. 

SvmLinkCount 

The current number of symbolic links in the fileset. 

2.2.42. Name Service Fileset Attribute Bits - ns_FilesetAttrBits_t 

Description 

Bits specifying the Name Service fileset attribute bits to retrieve or set. 

Format 

The ns FilesetAttrBits t has the following format: 

typedef u_signed64 ns_FilesetAttrBits_t; 

2.2.43. Name Service Object Handle Structure - ns_ObjHandle_t 

Description 

The Name Service object handle structure contains information that allows the Core Server to identify the 
metadata record for an object. 

Format 


The Name Service object handle structure has the following format: 

struct ns_ObjHandle { 

u_signed64 Objld; 
u_signed64 Fileld; 
byte Type; 

byte Flags; 

unsignedl6 Generation; 
hpss_uuid_t CoreServerUUID; 

} ; 

typedef struct ns_ObjHandle ns_ObjHandle; 
typedef ns_ObjHandle ns_ObjHandle_t; 

Obild 

Specifies a unique Core Server object identifier, the Relative Sequence Number (RSN) of the record 
containing the metadata for the object. 

Fileld 

If the Type field specifies a hardlink this is the RSN of the record containing the metadata for the original 
file. For all other Types this field is equal to the Objld. 

Type 

Specifies the ‘type’ of the object: file, directory, junction, symbolic link, or hard link. 

Flues 

Specifies a bit vector whose bits convey additional information about the object handle. The defined bit 
positions for the Flags field are: 
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NSOHFLAGFILESETROOT Handle is for the root node of a fileset. 

Generation 

Specifies a random number used to detect stale object handles. 

CoreServerVVID 

Specifies the UUID of the Core Server that issued this object handle. 

2.2.44. HPSS Object Handle Structure - hpss_object_handle_t 

Description 

This structure contains information pertaining to an HPSS object. 

Format 


The hpss object handle t has the following format: 

struct hpss_object_handle { 
signed32 ObjectPtr; 
hpss_uuid_t ObjectID; 
signed32 ObjectType; 
signed32 ConnectionType; 
signed32 ClientPtr; 

} ; 

typedef struct hpss_object_handle hpss_object_handle; 
typedef hpss_object_handle hpss_object_handle_t; 

ObjectPtr 

Pointer to an HPSS object. 

O bjectID 

Unique identifier for the object. 

ObiectTvpe 
The object type: 

CONNECTIONOBJECT 
SESSIONOBJECT 
Connection Type 
Connection type of the object. 

ClientPtr 

Pointer to the client. 

2.2.45. Purge Lock Flag - purgelock_flag_t 

Description 

Flag specifying whether a file should have its purgelock status set or cleared. 
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Format 


The purgelockflagt structure has the following format: 

typedef enum { 

PURGE_UNLOCK = 0 
PURGE_LOCK 
} purgelock_flag_t; 

2.2.46. Core Server Physical Volume Attributes - pv_list_element_t 

Description 

This structure contains physical volume location information for specified physical volume. 

Format 


/* purge unlock the file */ 
/* purge lock the file */ 


The Core Server physical volume attributes have the following format: 

typedef struct pv_list_element { 

char Name [HPSS_PV_NAME_SIZE] ; 
unsigned32 Flags; 

} pv_list_element_t; 

Name 

Specifies the physical volume name. 

Flues 

Specifies the location of the physical volume. The following constants may be set in this field: 

PVMOUNTSUCCESS 

P V_UNMOUNT_N OENT 

PVUNMOUNTSUCCESS 

PVONSHELF 

2.2.47. Core Server Physical Volume Attributes Conformant Array - 
pv_list_t 

Description 

The pv list t structure describes a template for a conformant array of Core Server Physical Volume 
Attribute elements. 


Format 


The Core Server physical volume attribute conformant array has the following format: 

struct pv_list { 
struct { 

u_int List_len; 

pv_list_element_t *List_val; 

} List; 

} ; 
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typedef struct pv_list pv_list; 
typedef pv_list pv_list_t; 


ListJen 

Specifies the number of physical volume attribute elements in the array. 

List val 

A conformant array of physical volume attribute elements. 

2.2.48. HPSS Security User Credentials - sec_cred_t 

Description 

The HPSS Security User Credentials structure contains information about the user credentials. This 
information can only be obtained by an authorized client using HPSS security mechanisms. 


The format of the sec cred t structure is: 


struct sec_cred { 
char 
char 
char 
char 

unsigned32 

unsigned32 

unsigned32 

hpss_uuid_t 

acct_rec_t 

acct_rec_t 

unsigned32 

unsigned32 

} ; 


Name[HPSS_MAX_USER_NAME]; 
RealmName[HPSS_MAX_REALM_NAME]; 
Directory[HPSS_MAX_PATH_NAME]; 
UserShell[HPSS_MAX_USER_SHELL]; 
Realmld; 

Uid; 

Gid; 

Uuid; 

DefAccount; 

CurAccount; 

NumGroups; 

AltGroups[HPSS_NGROUPS_MAX]; 


typedef struct sec_cred sec_cred; 
typedef sec_cred sec_cred_t; 


Name 
User name. 

RealmName 

Realm name where principal resides. 

Directory 

Directory name. 

UserShell 
User's shell. 

Realmld 

Identifier of realm where principal resides. 
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Unix user identifier. 


Gid 

Unix group identifier. 

Uuid 

Unique user identifier. 

D efAccount 

The accounting code that is used when a current account code has not been specified. 

CurAccount 

When a current accounting code is specified, this code is applied to new files or directories. 

NumGroups 

The number of groups to which this principal is a member. 

AltGroups 

An array of groups to which this principal is a member. 

2.2.49. Subsystem Statistics - subsys_stats_t 

Description 

This structure contains statistical information for a subsystem including counts of stages, migrates, purges, 
and deletions. In addition, the structure includes a timestamp indicating when the counts began. 

Format 


The subsystem statistics have the following format: 

typedef struct subsys_stats { 

unsigned32 StageCount; 

unsigned32 MigrationCount; 

unsigned32 PurgeCount; 

unsigned32 DeleteCount; 

timestamp_sec_t TimeLastReset; 

} subsys_stats_t; 

StaveCount 

Specifies the number of stages which have occurred since the last reset. 

MierationCount 

Specifies the number of migrations which have occurred since the last reset. 

PurseCount 

Specifies the number of purges which have occurred since the last reset. 

DeleteCount 
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Specifies the number of deletes which have occurred since the last reset. 
TimeLastReset 

Specifies the time of the last reset (all counts were set to 0). 

2.2.50. Timestamp Seconds Type - timestamp_sec_t 

Description 

This data type specifies a timestamp in seconds. 

Format 

The format for this data type is: 

typedef unsigned32 timestamp_sec_t; 


2.3. Network Options 

2.3.1. Network Options Functions 

2.3.1.1. netopt_FindEntry 

Purpose 

Returns an HPSS network option entry for the specified IP address. 

Synopsis 

#include "hpss_netopt.h" 
int 

netopt_FindEntry( 

unsigned int NetAddr, /* IN */ 

netopt_entry_t * *RetTableEntryPtr ); /* OUT */ 


Description 

The netopt_FindEntry function searches the HPSS network option entries for an entry that matches the IP 
address specified by NetAddr, and returns a pointer to the entry in the value pointed to by 
RetTableEntryPtr. 

Parameters 

NetAddr The IP address of the machine or network for which a match is requested in the 

HPSS network options table. 

RetTableEntryPtr Pointer to the area where the HPSS network option entry pointer will be returned. 

Return Values 

If an HPSS network option entry that corresponds to the specified IP address is found, then a value of zero 
is returned and a pointer to the entry is returned in the area specified by RetTableEntryPtr. Otherwise, a 
negative value is returned which describes the error, as defined below. 

Error Conditions 
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HPSS_ENOMEM 

HPSSENOENT 


HPSSESYSTEM 

See Also 


Could not allocate memory for the network options table. 

The HPSS network options configuration file does not exist or no entry could be 
found that corresponds to the specified IP address. 

An operating system service failed. 


netoptGetWriteSize. 

Notes 


None 

2.3.1.2. netopt_GetWriteSize 

Purpose 

Returns the size in bytes to be used for writes to the TCP/IP connection referred to by either a socket 
descriptor or IP address. 

Synopsis 

#include "hpss_netopt.h" 
int 

netopt_GetWriteSize( 

int SocketDescriptor 

unsigned int IpAddr ); 

Description 

The netopt_GetWriteSize function returns the configured size, in bytes, to be used for writing data to the 
connection referred to by either SocketDescriptor or NetAddr. The function searches the HPSS network 
option entries for an entry that matches the IP address specified by NetAddr, if non-zero and otherwise 
based on the local address corresponding to the socket referred to by SocketDescriptor. If an entry is found 
and contains a non-zero network write size, that value is returned; otherwise the environment variable 
HPSS_TCP_WRITESIZE is interrogated - if it is set and contains a non-zero value, that value is returned, 
otherwise zero is returned. 

Parameters 

SocketDescriptor File descriptor referring to the open TCP/IP connection over which the request is 
to be sent. 

IpAddr The IP address of the machine or network for which a match is requested in the 

HPSS network options table. 

Return Values 

The size, in bytes, that is configured for the specified network address is returned if any values have been 
specified. Otherwise the default value is returned. 

Error Conditions 

None. 


/* IN */ 
/* IN */ 


See Also 
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netoptFindEntry. 


Notes 


None. 

2.3.2. Network Options Data Definitions 
2.3.2.1. Network Options Entry - netopt_entry_t 

Description 

The Network Options Entry structure contains the configuration information for a particular network (IP) 
address. This information is used to allow different networking options to be utilized for different HPSS 
Mover and/or HPSS client machines and networks 


Format 


The Network Options Entry structure has the following format: 


typedef struct netopt_entry 
unsigned long 
unsigned long 
unsigned long 
unsigned long 
unsigned long 
unsigned long 
unsigned long 
unsigned long 
} netopt_entry_t; 


IPAddr; 
NetMask; 
RFC1323; 
SendSpace ; 
RecvSpace ; 
WriteSize; 
TCPNodelay; 
Reserved2 ; 


InAddr 

The IP address for this entry. 

NetMask 

The network mask to be applied to the incoming address to determine whether this entry applies to that 
address. 

RFC1323 

Indicates whether RFC 1323 (large TCP window size support) should be enabled for this address. A value 
of zero indicates that RFC 1323 support should be disabled; a non-zero value indicates that RFC 1323 
support should be enabled. 

SendSpace 

The value to be used for the socket send buffer size. 


RecvSpace 

The value to be used for the socket receive buffer size. 


WriteSize 

The maximum number of bytes that should be written to a network connection corresponding to this entry 
with a single EO request. 
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TCPNodelav 

Indicates whether the algorithm employed to try and coalesce small writes to a TCP connection should be 
disabled. A value of zero indicates that the algorithm should not be disabled; a non-zero value indicates 
that the algorithm should be disabled. 

Reserved.2 

This field is currently unused. 
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Chapter 3. Math Library 

This chapter specifies the HPSS 64-bit arithmetic programming interface. Specifically, the following information is 
provided: 

• Application Programming Interfaces (APIs) 

• Data Definitions 

API Interfaces 

This section describes all API interfaces which are provided for use by another HPSS subsystem or by a client exter¬ 
nal to HPSS. The API interface specification includes the following information: 

• Name 

• Synopsis 

• Description 

• Parameters 

• Return Values 

• Error Conditions 

• See Also 

• Notes 

3.1.1. add64m 

Purpose 

Add two unsigned 64-bit integers. 

Synopsis 

#include "u_signed64.h" 

u_signed64 add64m( 

u_signed64 112, /* IN */ 
u_signed64 112) ; /* IN */ 

Description 

The add64m macro is called to add two unsigned 64-bit integers. 

Parameters 

111 Specifies the first unsigned 64-bit integer. 

112 Specifies the second unsigned 64-bit integer. 

Return Values 

Upon completion, an unsigned 64-bit integer is returned. 

Error Conditions 

None. 
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See Also 


add64_3m. 

Notes 

None. 

3.1.2. add64_3m 

Purpose 

Add two unsigned 64-bit integers and store the result in a separate integer field. 

Synopsis 

#include "u_signed64.h" 

void add64_3m( 

u_signed64 112, /* OUT */ 

u_signed64 112 , /* IN */ 

u_signed64 113 ); /* IN */ 

Description 

The add64_3m macro is called to add two unsigned 64-bit integers and store the result into a third unsigned 
64-bit integer. 

Parameters 

111 Specifies the result of the addition of the 2 unsigned 64-bit operands. 

112 Specifies the first unsigned 64-bit integer addition operand. 

113 Specifies an unsigned 64-bit integer to add to the first operand. 

Return Values 

None. The result of the addition is stored in the first parameter. 

Error Conditions 

None. 

See Also 

add64m. 

Notes 

None. 

3.1.3. and64m 

Purpose 

Find the bitwise AND of two unsigned 64-bit values. 

Synopsis 
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#include "u_signed64.h" 

u_signed64 and64m ( 

u_signed64 111 , /* IN */ 
u_signed64 112 ) ; /* IN */ 

Description 

The and64m macro is called to perform an AND operation of two unsigned 64-bit integer values. 

Parameters 

111 Specifies the first unsigned 64-bit integer. 

112 Specifies the second unsigned 64-bit integer. 

Return Values 

Upon completion, an unsigned 64-bit integer is returned. 

Error Conditions 

None. 

See Also 

not64m, or64m. 

Notes 

None. 

3.1.4. bld64m 

Purpose 

Build an unsigned 64-bit integer from two unsigned 32-bit integers. 

Synopsis 

#include "u_signed64.h" 

u_signed64 bld64m( 

unsigned32 11 , /* IN */ 
unsigned32 12 ) ; /* IN */ 

Description 

The bld64m macro is called to construct an unsigned 64-bit integer from 2 unsigned 32-bit integers. 

Parameters 

11 Specifies the unsigned 32-bit integer which will occupy the high order portion of 
the unsigned 64 -bit integer. 

12 Specifies the unsigned 32-bit integer which will occupy the low order portion of 
the unsigned 64 -bit integer. 

Return Values 
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Upon completion, an unsigned 64-bit integer is returned. 

Error Conditions 

None. 

See Also 

cast64m. 

Notes 

none. 

3.1.5. cast64m 

Purpose 

Cast an unsigned 32-bit integer into an unsigned 64-bit integer. 

Synopsis 

#include "u_signed64.h" 

u_signed64 cast64m( 

unsigned32 11 ); /* IN */ 

Description 

The cast64m macro is called to cast an unsigned 32-bit integer into an unsigned 64-bit integer. 

Parameters 

11 Specifies an unsigned 32-bit integer to be cast into an unsigned 64- bit integer. 

Return Values 

Upon completion, an unsigned 64-bit integer is returned. 

Error Conditions 

None. 

See Also 

cast32m. 

Notes 

None. 

3.1.6. div64m 

Purpose 

Divide an unsigned 64-bit integer by an unsigned 32-bit integer. 

Synopsis 

#include "u_signed64.h" 
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u_signed64 div64m( 

u_signed64 111 , /* IN */ 
unsigned32 11 ); /* IN */ 

Description 

The div64m macro is called to divide an unsigned 64-bit value by an unsigned 32-bit value. 

Parameters 

111 Specifies an unsigned 64-bit integer numerator. 

II Specifies an unsigned 32-bit integer divisor. 

Return Values 

Upon completion, an unsigned 64-bit integer is returned. 

Error Conditions 

None. 

See Also 

div2x64m, div_cl64m, div_2xcl64m, mod64m, mod2x64m. 

Notes 

None. 

3.1.7. div2x64m 

Purpose 

Divide an unsigned 64-bit integer by an unsigned 64-bit integer. 

Synopsis 

#include "u_signed64.h" 

u_signed64 div2x64m( 

u_signed64 111 , /* IN */ 
u_signed64 112 ); /* IN */ 

Description 

The div2x64m macro is called to divide an unsigned 64-bit value by an unsigned 64-bit value. 

Parameters 

III Specifies an unsigned 64-bit integer numerator. 

112 Specifies an unsigned 64-bit integer divisor. 

Return Values 

Upon completion, an unsigned 64-bit integer is returned. 

Error Conditions 
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None. 


See Also 

div64m, div_cl64m, mod64m, mod2x64m. 

Notes 

None. 

3.1.8. div_cl64m 

Purpose 

Divide an unsigned 64-bit integer by an unsigned 32-bit integer and return the integer ceiling of the result. 
Synopsis 

#include "u_signed64.h" 

u_signed64 div_cl64m( 

u_signed64 111 , /* IN */ 
unsigned32 11 ); /* IN */ 

Description 

The div_cl64m macro is called to return the integer ceiling resulting from the division of an unsigned 64-bit 
value by an unsigned 32-bit value. 

Parameters 

111 Specifies an unsigned 64-bit integer numerator. 

11 Specifies an unsigned 32-bit integer divisor 

Return Values 

Upon completion, an unsigned 64-bit integer is returned. 

Error Conditions 

None. 

See Also 

div64m, div2x64m, div_2xcl64m, mod64m. 

Notes 

None. 

3.1.9. div_2xcl64m 

Purpose 

Divide an unsigned 64-bit integer by an unsigned 64-bit integer and return the integer ceiling of the result. 
Synopsis 

#include "u_signed64.h" 
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u_signed64 div_2xcl64m( 

u_signed64 111 , /* IN */ 
u_signed64 112 ); /* IN */ 

Description 

The div_2xcl64m macro is called to return the integer ceiling resulting from the division of an unsigned 64- 
bit value by an unsigned 64-bit value. 

Parameters 

111 Specifies an unsigned 64-bit integer numerator. 

112 Specifies an unsigned 64-bit integer divisor. 

Return Values 

Upon completion, an unsigned 64-bit integer is returned. 

Error Conditions 

None. 

See Also 

div64m, div2x64m, div_cl64m, mod64m, mod2x4m. 

Notes 

None. 

3.1.10. eqz64m 

Purpose 

Determine if an unsigned 64-bit integer is zero. 

Synopsis 

#include "u_signed64.h" 
int eqz64m ( 

u_signed64 III); /* IN */ 

Description 

The eqz64m macro is called to check if an unsigned 64-bit integer equals zero. 

Parameters 

111 Specifies the unsigned 64-bit integer. 

Return Values 

1 is returned if 111 equals zero. Otherwise 0 is returned. 

Error Conditions 

None. 
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See Also 


eq64m, ge64m, gt64m, le64m, lt64m, neqz64m, neq64m. 

Notes 

None. 

3.1.11. eq64m 

Purpose 

Compare two unsigned 64-bit integers for equality. 

Synopsis 

#include "u_signed64.h" 
int eq64m ( 

u_signed64 112, /* IN */ 
u_signed64 112 ) ; /* IN */ 

Description 

The eq64m macro is called to check if two unsigned 64-bit integer values are equal. 

Parameters 

111 Specifies the first unsigned 64-bit integer. 

112 Specifies the second unsigned 64-bit integer. 

Return Values 

1 is returned if 111 = 112. Otherwise 0 is returned. 

Error Conditions 

None. 

See Also 

eqz64m, ge64m, gt64m, le64m, lt64m, neqz64m, neq64m. 

Notes 

None. 

3.1.12. ge64m 

Purpose 

Perform greater than or equal check between two unsigned 64-bit integers. 

Synopsis 

#include "u_signed64.h" 
int ge64m( 

u_signed64 111, /* IN */ 
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_signed64 112 ) ; /* IN */ 


Description 

The ge64m macro is called to determine if the first unsigned 64-bit integer value is greater than or equal to 
the second unsigned 64-bit integer. 

Parameters 

111 Specifies the first unsigned 64-bit integer. 

112 Specifies the second unsigned 64-bit integer. 

Return Values 

1 is returned if 111 >=112. Otherwise 0 is returned. 

Error Conditions 

None. 

See Also 

eqz64m, eq64m, gt64m, le64m, lt64m, neqz64m, neq64m. 

Notes 

None. 

3.1.13. gt64m 

Purpose 

Perform greater than check between two unsigned 64-bit integers. 

Synopsis 

#include "u_signed64.h" 
int gt64m( 

u_signed64 III, /* IN */ 
u_signed64 112 ); /* IN */ 

Description 

The gt64m macro is called to determine if the first unsigned 64-bit integer value is greater than the second 
unsigned 64-bit integer. 

Parameters 

111 Specifies the first unsigned 64-bit integer. 

112 Specifies the second unsigned 64-bit integer. 

Return Values 

1 is returned if 111 > 112. Otherwise 0 is returned. 

Error Conditions 
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None. 


See Also 

eqz64m, eq64m, ge64m, le64m, lt64m, neq64m. 

Notes 

None. 

3.1.14. high32m 

Purpose 

Extract the high order 32-bits from an unsigned 64-bit integer. 

Synopsis 

#include "u_signed64.h" 

unsigned32 high32m( 

u_signed64 111 ) ; /* IN */ 

Description 

The high32m macro is called to extract an unsigned 32-bit integer from the high order 32-bits of an 
unsigned 64-bit integer. 

Parameters 

111 Specifies the unsigned 64-bit integer. 

Return Values 

Upon completion, an unsigned 32-bit integer is returned. 

Error Conditions 

None. 

See Also 

low32m. 

Notes 

None. 

3.1.15. Ie64m 

Purpose 

Perform less than or equal check between two unsigned 64-bit integers. 

Synopsis 

#include "u_signed64.h" 
int le64m( 
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u_signed64 111 , /* IN */ 
u_signed64 112 ); /* IN */ 


Description 

The le64m macro is called to determine if the first unsigned 64-bit integer value is less than or equal to the 
second unsigned 64-bit integer. 

Parameters 

111 Specifies the first unsigned 64-bit integer. 

112 Specifies the second unsigned 64-bit integer. 

Return Values 

1 is returned if HT.^Sf 112. Otherwise 0 is returned. 

Error Conditions 

None. 

See Also 

eqz64m, eq64m, ge64m, gt64m, lt64m, neq64m. 

Notes 

None. 

3.1.16. low32m 

Purpose 

Extract the low order 32-bits from an unsigned 64-bit integer. 

Synopsis 

#include "u_signed64.h" 

unsigned32 low32m( 

u_signed64 111 ); /* IN */ 

Description 

The low32m macro is called to extract an unsigned 32-bit integer from the low order 32-bits of an unsigned 
64-bit integer. 

Parameters 

111 Specifies the unsigned 64-bit integer. 

Return Values 

Upon completion, a 32-bit unsigned integer is returned. 

Error Conditions 

None. 
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See Also 


high32m. 

Notes 

None. 

3.1.17. It64m 

Purpose 

Perform less than check between two unsigned 64-bit integers. 

Synopsis 

#include "u_signed64.h" 
int lt64m( 

u_signed64 112, /* IN */ 
u_signed64 112 ); /* IN */ 

Description 

The lt64m macro is called to determine if the first unsigned 64-bit integer value is less than the second 
unsigned 64-bit integer. 

Parameters 

111 Specifies the first unsigned 64-bit integer. 

112 Specifies the second unsigned 64-bit integer. 

Return Values 

1 is returned if 111 < 112. Otherwise 0 is returned. 

Error Conditions 

None. 

See Also 

eqz64m, eq64m, ge64m, gt64m, le64m, neq64m. 

Notes 

None. 

3.1.18. mod64m 

Purpose 

Determine the remainder on division of an unsigned 64-bit integer by an unsigned 32-bit integer. 
Synopsis 

#include "u_signed64.h" 
u_signed64 mod64m( 
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u_signed64 111 , /* IN */ 
unsigned32 11 ); /* IN */ 


Description 

The mod64m macro is called to perform a modulus of an unsigned 64-bit integer value by an unsigned 32- 
bit integer value. 

Parameters 

111 Specifies the unsigned 64-bit integer to divide. 

II Specifies the unsigned 32-bit integer divisor. 

Return Values 

Upon completion, an unsigned 64-bit integer is returned. 

Error Conditions 

None. 

See Also 

div64m, div2x64m, div_cl64m, div_2xcl64m, mod2x64m. 

Notes 

None. 

3.1.19. mod2x64m 

Purpose 

Determine the remainder on division of an unsigned 64-bit integer by an unsigned 64-bit integer. 

Synopsis 

#include "u_signed64.h" 

u_signed64 mod2x64m( 

u_signed64 111 , /* IN */ 
u_signed64 112 ); /* IN */ 

Description 

The mod2x64m macro is called to perform a modulus of an unsigned 64-bit integer value by an unsigned 
64- bit integer value. 

Parameters 

III Specifies the unsigned 64-bit integer to modulus. 

112 Specifies the unsigned 64-bit integer modulus value. 

Return Values 

Upon completion, an unsigned 64-bit integer is returned. 

Error Conditions 
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None. 


See Also 

div64m, div2x64, div_cl64m, div_2xcl64m, mod64m. 

Notes 

None. 

3.1.20. mul64m 

Purpose 

Multiply an unsigned 64-bit integer by an unsigned 32-bit integer. 

Synopsis 

#include "u_signed64.h" 

u_signed64 mul64m( 

u_signed64 111 , /* IN */ 
unsigned32 11 ); /* IN */ 

Description 

The mul64m macro is called to multiply an unsigned 64-bit integer value by an unsigned 32-bit integer 
value. 

Parameters 

111 Specifies the unsigned 64-bit integer multiplier. 

11 Specifies the unsigned 32-bit integer multiplier. 

Return Values 

Upon completion, an unsigned 64-bit integer is returned. 

Error Conditions 

None. 

See Also 

None. 

Notes 

None. 

3.1.21. neqz64m 

Purpose 

Determine if an unsigned 64-bit integer is nonzero. 

Synopsis 

#include "u_signed64.h" 
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int neqz64m( 

u_signed64 111 ) ; /* IN */ 

Description 

The neqz64m macro is called to check if an unsigned 64-bit integer is nonzero. 

Parameters 

111 Specifies the unsigned 64-bit integer. 

Return Values 

1 is returned if 111 != 0. Otherwise 0 is returned. 

Error Conditions 

None. 

See Also 

eqz64m, eq64m, ge64m, gt64m, le64m, lt64m, neq64m. 

Notes 

None. 

3.1.22. not64m 

Purpose 

Perform a bitwise NOT of an unsigned 64-bit integer. 

Synopsis 

#include "u_signed64.h" 

u_signed64 not64m( 

u_signed64 III); /* IN */ 

Description 

The not64m macro is called to perform a bitwise NOT of an unsigned 64-bit integer value. 

Parameters 

111 Specifies an unsigned 64-bit integer. 

Return Values 

Upon completion, an unsigned 64-bit integer is returned. 

Error Conditions 

None. 

See Also 

and64m, or64m. 
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Notes 


None. 

3.1.23. or64m 

Purpose 

Find the bitwise OR of two unsigned 64-bit values. 

Synopsis 

#include "u_signed64.h" 

u_signed64 or64m ( 

u_signed64 112, /* IN */ 
u_signed64 112 ) ; /* IN */ 

Description 

The or64m macro is called to perform an OR operation of two unsigned 64-bit integer values. 

Parameters 

111 Specifies the first unsigned 64-bit integer. 

112 Specifies the second unsigned 64-bit integer. 

Return Values 

Upon completion, an unsigned 64-bit integer is returned. 

Error Conditions 

None. 

See Also 

and64m, not64m. 

Notes 

None. 

3.1.24. shl64m 

Purpose 

Shift an unsigned 64-bit integer left by an unsigned 32-bit unsigned integer amount. 

Synopsis 

#include "u_signed64.h" 

u_signed64 shl64m( 

u_signed64 111, /* IN */ 
unsigned32 11); /* IN */ 

Description 
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The shl64m macro is called to shift an unsigned 64-bit integer left by an unsigned 32-bit integer count. 

Parameters 

111 Specifies an unsigned 64-bit integer to be shifted. 

II Specifies an unsigned 32-bit integer shift count. 

Return Values 

Upon completion, an unsigned 64-bit integer is returned. 

Error Conditions 

None. 

See Also 

shr64m. 

Notes 

None. 

3.1.25. shr64m 

Purpose 

Shift an unsigned 64-bit integer right by an unsigned 32-bit integer amount. 

Synopsis 

#include "u_signed64.h" 

u_signed64 shr64m( 

u_signed64 112, /* IN */ 
unsigned32 11); /* IN */ 

Description 

The shr64m macro is called to shift an unsigned 64-bit integer right by an unsigned 32-bit integer count. 

Parameters 

III Specifies an unsigned 64-bit integer to be shifted. 

11 Specifies an unsigned 32-bit integer shift count. 

Return Values 

Upon completion, an unsigned 64-bit integer is returned. 

Error Conditions 

None. 

See Also 

shl64m. 

Notes 
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None. 


3.1.26. sub64m 

Purpose 

Subtract two unsigned 64-bit integers. 

Synopsis 

#include "u_signed64.h" 

u_signed64 sub64m( 

u_signed64 111, /* IN */ 
u_signed64 112); /* IN */ 


Description 

The sub64m macro is called to subtract two unsigned 64-bit integer values. 

Parameters 

111 Specifies an unsigned 64-bit integer. 

112 Specifies an unsigned 64-bit integer to subtract from the first operand. 

Return Values 

Upon completion, an unsigned 64-bit integer is returned. 

Error Conditions 

None. 


See Also 


sub64_3m. 


Notes 


None. 

3.1.27. sub64_3m 

Purpose 

Subtract two unsigned 64-bit integers and store the result in a separate integer field. 

Synopsis 

#include "u_signed64.h" 

void sub64m_3m( 

u_signed64 111, /* OUT */ 

u_signed64 112, /* IN */ 

u_signed64 113 ); /* IN */ 


Description 
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The sub64_3m macro is called to subtract two unsigned 64-bit integers and store the result into a third 
unsigned 64-bit integer. 

Parameters 

111 Specifies the result of the subtraction of the 2 unsigned 64-bit operands. 

112 Specifies the first unsigned 64-bit integer subtraction operand. 

113 Specifies an unsigned 64-bit integer to subtract from the first operand. 

Return Values 

None. The result of the subtraction is stored in the first parameter. 

Error Conditions 

None. 


See Also 


sub64m. 


Notes 

None. 

3.2. Data Definitions 

This section describes key internal data definitions and all externally used data definitions which are provided by this 
subsystem. A data definition may be represented by constructs such as data structures and constants. For each data 
definition, a description, format (including parameter descriptions), and clients which access the data definition are 
provided. 

3.2.1. u_signed64 

Description 

u_signed64 is the type for an unsigned 64-bit integer. 

Format 


For big-endian platforms, the u_signed64 type is defined in the u_signed64.h file as follows: 

typedef struct{ 

unsigned long h; 
unsigned long 1; 

} u_signed64; 


For little-endian platforms, the u_signed64 type is defined in the u_signed64.h file as follows: 

typedef struct{ 

unsigned long 1; 
unsigned long h; 

} u_signed64; 
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3.2.2. unsigned32 

Description 

unsigned32 is the type for an unsigned 32-bit integer. 

Format 


The unsigned32 type is defined in the u_signed64.h file as follows: 

typedef unsigned long unsigned32; 
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Chapter 4. Site Interfaces 

This chapter describes all Site Interfaces which are provided for use by two shared libraries 
(Account Validation site policy and Gatekeeping site policy) which will each be dynamically 
loaded with the Gatekeeper Server. The Site interface specification includes the following 
information: 

• Name 

• Purpose 

• Synopsis 

• Description 

• Parameters 

• Return Values 

• Error Conditions 

• See Also 

• Clients 

• Notes 

• Example Usage 

4.1. Gatekeeping 

This section describes the Gatekeeping Site Interfaces. Function definitions for these Site Interfaces are provided 
with the HPSS release, thus the Gatekeeper Server installed by default does NO gatekeeping. Sites will need to 
enhance these interfaces to implement local policy rules. The site interface code exists in /opt/hpss/src/sitelib/gk. 
Each Site Interface will be called by a Gatekeeping Service API. Please refer to the "Example Usage" section of 
each Site Interface for example "pseudo code" implementation details of a site defined policy. 

Please note that the code listed here is merely to give an idea of example uses. It has not been tested in an actual 
system. 

4.1.1. gk_site_Close 

Purpose 

This is an internal, site defined-and-implemented function that is called by the Gatekeeper whenever a file is 
closed. This function is not an RPC. It is a call to a procedure in a shared library. 

Synopsis 

signed32 
gk_site_Close ( 

hpss_uuid_t ControlNo) ; /* IN */ 


Description 

This function is written by the customer site. It will be called by gk_Close while processing a close of an 
HPSS file. 


HPSS Programmer's Reference 
Release 6.2 (Revision 2.0) 


July 2008 


245 




Parameters 


ControlNo Unique identifier for the opened file which is now being closed. This number 

was generated by the Gatekeeper and passed into gk_site_Open or 
gksiteOpenStats. 

Return Values 

Upon successful completion, a value of zero (0) is returned. Non-zero values are described in the Error 
Conditions. 

Error Conditions 

The gk_site_Close routine is unsuccessful if any of the following are true: 

HPSSEAGA1N Resources are temporarily unavailable. 

HPSS ENOENT Could not find an entry matching the ControlNo field in Entrylnfo. 

HPSS ENOTREADY Initialization has not completed. 

See Also 

gkClose, gkOpen, gksiteOpen, and gk site OpenStats. 

Clients 

Gatekeeper. 

Notes 

None. 

Example Usage 

Log entrance of this routine to the Site Policy Logfile. 

Lock the Request Cache. 

Lookup the ControlNo in the Request Cache. 

If not found, then 

ft must have already been removed. 

NOTE: There is a situation in which this will happen. 

ft could be that the GK was bounced while the Core Server was 
handling the termination. So, don't do anything rash. 

Unlock the Request Cache. 

Log an Error to the Site Policy Logfile. 
return. 

If the Request was NOT an AuthorizedCaller request, then 
If the State of this request is GOOD, then 
Decrement the Host Count of the good opens pending. 
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Decrement the User Count of the good opens pending. 

Decrement the global number of good opens pending. 

Else if the State of this request is RETRY, then 
Decrement the global number of retry opens pending. 

If the Request was in a retry state due to the host policy 
denying the open, then 

Decrement the Host's Count of the retry opens pending. 

If the Request was in a retry state due to the user policy 
denying the open, then 

Decrement the User's Count of the retry opens pending. 

Delete the Request from the Request Cache. 

Unlock the Request Cache. 

Log exit of this routine to the Site Policy Logfile. 

4.1.2. gk_site_Create 

Purpose 

This is an internal, site defined-and-implemented function that implements site policies which decide if a 
caller is authorized to create the file now, later, or not at all. This function is not an RPC. It is a call to a 
procedure in a shared library. 

Synopsis 

signed32 

gk_site_Create ( 

gk_EntryInfo_t Entrylnfo , /* IN */ 

unsigned32 *Wa±tT±meP) /* OUT */ 


Description 

This function is written by the customer site. It is called by gk_Create whenever an HPSS fde create 
occurs. 

Parameters 

Entrylnfo Information about the file being created. 

WaitTimeP A pointer to the number of seconds to wait before retrying a request. 

Return Values 

Upon successful completion, a value of zero (0) is returned which tells the Gatekeeper to continue with the 
create request. After the Gatekeeper has returned success to the caller, it expects gk_site_CreateComplete 
to be called when the file has been created or if an error occurs. 

All non-zero return values will be treated as errors, thus the client will do the appropriate error handling and 
terminate the create request. Non-zero error values are described in the Error Conditions. 
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Error Conditions 


The gk_site_Create routine is unsuccessful if any of the following are true: 


HPSSEACCES 

HPSSEAGAIN 

HPSSENOTREADY 

HPSSEPERM 

HPSSERETRY 

HPSSETHRESHOLDDENY 


HPSS_EUSER_DENY 


Permission is denied. 

Resources are temporarily unavailable. 

Initialization has not completed. 

The operation is not permitted. 

The operation should be retried after the delay, in seconds, returned by 
the WaitTimeP parameter. 

This error code is returned to deny access due to exceeding a 
threshold. The Core Server will return this error to the Client API. The 
Client API will map this error into EBUSY before returning the error 
code to the application. 

This error code is returned to deny access to a particular user. The 
Core Server will return this error to the Client API. The Client API 
will map this error into EACCESS before returning the error code to 
the application. 


See Also 


gk Create, gk CreateComplete, gk site CreateComplete and gksiteCreateStats. 

Clients 


Gatekeeper. 

Notes 


Routine gk_site_CreateStats is called instead of gk_site_Create whenever an HPSS file create occurs 
from an authorized caller when authorized caller requests are monitored. 

If the operation should be retried, HPSS RETRY is returned and the number of seconds the caller should 
wait before retrying is returned in the WaitTimeP parameter. If the site does not specify the WaitTimeP 
parameter (returns 0), the default value from the Gatekeeper’s specific configuration field DefaultWaitTime 
is used instead. 

Example Usage 

Log entrance of this routine to the Site Policy Logfile using the 
Requestld passed in the Entrylnfo. 

Initialize the WaitTimeP return parameter to 0. 

If we're not monitoring for creates, then 
Log an ALARM Error to the Site Policy Logfile. 

Return, but don't return an error status — just let the create continue. 

If there is a no Site Policy file 
Log an Error to the Site Policy Logfile. 


HPSS Programmer's Reference 
Release 6.2 (Revision 2.0) 


July 2008 


248 



Return good status. 

Lock the Request Cache. 

Find the Request in the Request Cache. 

If not found, then 

Create a new Request Entry and add it to the Request Cache. 

Else 

The Request is being retried. 

If there exists a "Maximum Number of Creates Per Host Policy", then 
Note: Translating socket address into hostnames is expensive, so 
maintain a cache to translate HostAddrs to HostNames. 

Lock the HostAddrToHostName Cache. 

Lookup the Entrylnfo.HostAddr in the HostAddrToHostName Cache. 

If it doesn't exist, then 
hpssGetHostByAddr 

If Error returned by multithreaded safe get host by addr lookup, then 
Log an error to the Site Policy Logfile. 

Delete the Request from the Request Cache. 

Unlock all locks. 

Return HPSSEFAULT. 

Create, initialize and add a new HostAddrToHostName cache entry. 
Save away the HostName. 

Unlock the HostAddrToHostName Cache. 

Lookup the HostName in the Host Entry Cache. 

Note: The Host Entry Cache is sharing the Request Cache Lock. 

If not found, then 

Create a new Host Entry and add it to the Host Cache. 

If the Host Entry's good creates pending >= Maximum Creates Per Host, 
then 

Mark this request as a RETRY due to host policy denial. 

Set Error to HPSS ERETRY. 
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If the Request was not originally a RETRY, then 
Increment the retry creates pending in the Host Entry. 

If there exists a "Maximum Number of Creates Per User Policy" AND Error 
wasn't set in the Host Policy code above, then 

Lookup the Userld/Realmld pair in the User Entry Cache. 

Note: The Userid and Realmld together will uniquely identify a 
particular user in a federated name space (cross realm) 
environment. 

Note: The User Entry Cache is sharing the Request Cache Lock. 

If not found, then 

Create a new User Entry and add it to the User Cache. 

If the User Entry's good creates pending >= Maximum Creates Per User, 
then 

Mark this request as a RETRY due to user policy denial. 

Set Error to HPSSERETRY. 

If the Request was not originally a RETRY, then 
Increment the retry creates pending in the User Entry. 

If we want to return HPSS ERETRY, then 
If this originally wasn't a retry request (i.e. first delay of request), 
then 

Increment the global retry creates pending count. 

Increment the RetryCount associated with the Request Entry. 

Mark the Request Entry's state as RETRY. 

Compute the WaitTime corresponding to the number of seconds to wait 
before the Client API will retry this request. 

Else if no Error, then 

Increment the global good creates pending count. 

Mark the Request Entry's state as GOOD. 
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If this request is being retried again, then 
Decrement the global retry creates pending count. 

If Host policy exists, then 

Decrement the Host Entry's good creates pending count. 

If this request was previously retried due to host policy denial, then 
Decrement the Host Entry's retry creates pending count. 

If User policy exists, then 

Decrement the User Entry's good creates pending count. 

If this request was previously retried due to user policy denial, then 
Decrement the Host User's retry creates pending count. 

Unlock the Request Cache. 

Log exit of this routine to the Site Policy Logfile. 

Return the status. 

4.1.3. gk_site_CreateComplete 

Purpose 

This is an internal, site defined-and-implemented function that is called by the Gatekeeper when a file create 
has completed. This function is not an RPC. It is a call to a procedure in a shared library. 

Synopsis 

signed32 

gk_site_CreateComplete ( 

hpss_uuid_t ControlNo) ; /* IN */ 

Description 

This function is written by the customer site. It will be called by gk_CreateComplete while processing a 
file create completion of an HPSS file. 

Parameters 

ControlNo Unique identifier for the created file which is now being completed. This 

number was generated by the Gatekeeper and passed into gk_site_Create or 
gksiteCreateStats. 

Return Values 

Upon successful completion, a value of zero (0) is returned. Non-zero values are described in the Error 
Conditions. 

Error Conditions 

The gk_site_CreateComplete routine is unsuccessful if any of the following are true: 
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HPSSEAGAIN Resources are temporarily unavailable. 

HPSSENOENT Could not find an entry matching the ControlNo field in Entrylnfo. 

HPSS ENOTREADY Initialization has not completed. 

See Also 

gkCreate, gkCreateComplete, gksiteCreate and gksiteCreateStats. 

Clients 

Gatekeeper. 

Notes 

None. 

Example Usage 

Please see gk_site_Close. 

4.1.4. gk_site_CreateStats 

Purpose 

This is an internal, site defmed-and-implemented function that is called asynchronously by the Gatekeeper 
when an authorized caller is creating a file. It is only called when authorized caller requests and create 
requests are being monitored. This function is not an RPC. It is a call to a procedure in a shared library. 

Synopsis 

void 

gk_site_CreateStats ( 

gk_Entry!nfo_t Entrylnfo) ; /* IN */ 


Description 

This function is written by the customer site. It is called asynchronously by gk_Create whenever an HPSS 
file create occurs from an authorized caller when both create requests and authorized caller requests are 
monitored. 

Parameters 

Entrylnfo Information about the file being created. 

Return Values 

None. 

Error Conditions 

None. 


See Also 


gk Create, gk CreateComplete, gk site Create and gk site CreateComplete. 

Clients 
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Gatekeeper. 


Notes 

Routine gk_site_CreateStats is called instead of gk_site_Create whenever an HPSS file create occurs 
from an authorized caller when authorized caller requests are monitored. 

The Gatekeeper will queue all asynchronous calls to the site interfaces so that they are processed in the 
order they are received. For example, if a site is monitoring authorized caller, create and open requests and 
an authorized caller create request is issued before an authorized caller open request, then the Gatekeeper 
will queue these requests so that gksiteCreateStats is called before gk_site_OpenStats. 

Example Usage 

Log entrance of this routine to the Site Policy Logfile using the 
Requestld passed in the Entrylnfo. 

If we're not monitoring for creates, then 
Log an ALARM Error to the Site Policy Logfile. 

Return. 

If there is a no Site Policy file 
Log an Error to the Site Policy Logfile. 

Return. 

Lock the Request Cache. 

Find the Request in the Request Cache. 

If not found, then 

Create a new Request Entry and add it to the Request Cache. 

If there exists a "Maximum Number of Creates Per Host Policy", then 
Note: Translating socket address into hostnames is expensive, so 
maintain a cache to translate HostAddrs to HostNames. 

Lock the HostAddrToHostName Cache. 

Lookup the Entrylnfo.HostAddr in the HostAddrToHostName Cache. 

If it doesn't exist, then 
hpssGetHostByAddr 

If Error returned by multithreaded safe get host by addr lookup, then 
Log an error to the Site Policy Logfile. 
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Delete the Request from the Request Cache. 
Unlock all locks. 


Return. 

Create, initialize and add a new HostAddrToHostName cache entry. 

Save away the HostName. 

Unlock the HostAddrToHostName Cache. 

Lookup the HostName in the Host Entry Cache. 

Note: Assume the Host Entry Cache is sharing the Request Cache Lock. 

If not found, then 

Create a new Host Entry and add it to the Host Cache. 

If there exists a "Maximum Number of Creates Per User Policy", then 

Lookup the Userld/Realmld pair in the User Entry Cache. 

Note: The Userid and Realmld together will uniquely identify a 
particular user in a federated name space (cross realm) 
environment. 

Note: The User Entry Cache is sharing the Request Cache Lock. 

If not found, then 

Create a new User Entry and add it to the User Cache. 

Mark the Request Entry's state as GOOD. 

Unlock the Request Cache. 

Log exit of this routine to the Site Policy Logfile. 

Return. 

4.1.5. gk_site_GetMonitorTypes 

Purpose 

This is an internal, site defined-and-implemented function that is called by the Gatekeeper get the types of 
items being monitored. This function is not an RPC. It is a call to a procedure in a shared library. 

Synopsis 

signed32 
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gk_site_GetMonitorTypes ( 

u_signed64 MonitorTypeBitsP ); /* OUT */ 


Description 

This interface will lookup the local site policies to determine which request types are being monitored. It 
will then return a bitvector of items being monitored. The Core Server will call gk_GetMonitorTypes 
when (re)connecting to the Gatekeeper to learn which request types are being monitored so that it can call 
the Gatekeeper appropriately. The Gatekeeper will call gk_site_GetMonitorTypes. Currently the 
following request types can be monitored: authorized caller, create, open, and stage. 

It is important that the Site Interfaces return a status in a timely fashion. Create, open, and stage requests 
from XFS, NFS, and MPS (authorized callers) are timing sensitive, thus the Site Interfaces won’t be 
permitted to delay or stop these requests, however the Site Interfaces may choose to be involved in keeping 
statistics on these requests by monitoring requests from authorized callers. 

Parameters 

MonitorTypeBitsP A bit vector (0 origin array of bits) in which the appropriate bit is set (on) for 

each request type that is currently being monitored. Request types index are: 

GKMONITORAUTHORIZEDCALLER 0 
GKMONITORCREATE 1 

GKMONITOROPEN 2 

GKMONITORSTAGE 3 


Return Values 

Upon successful completion, a value of zero (0) is returned. Non-zero values are described in the Error 
Conditions. 

Error Conditions 

The gk_site_GetMonitorTypes routine is unsuccessful if any of the following are true: 

HPSS EAGAIN Resources are temporarily unavailable. 

See Also 


gkGetMonito r Typ es. 


Clients 

Gatekeeper 

Notes 


The following table describes which Site Interface will be called for each request type when authorized 
caller requests are monitored. 


Request Type Authorized Caller 

Create gksiteCreateStats 

Open gksiteOpenStats 

Stage gk_site_StageStats 


All Other Users 

gksiteCreate 

gksiteOpen 

gk_site_Stage 
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Example Usage 

Log entrance of this routine to the Site Policy Logfile. 

Set the bits corresponding to what we're monitoring in the MonitorTypeBitsP. 

(e.g. *MonitorTypeBitsP = orbit64m(*MonitorTypeBitsP, GK MONITOR OPEN)) 

Log exit of this routine to the Site Policy Logfile. 

Return status. 

4.1.6. gk_site_lnit 

Purpose 

This is an internal, site defined and implemented function that is called when the Gatekeeper is 
(re) initialized. This function is used to do whatever initialization is needed by the site module. This 
function is not an RPC. It is a call to a procedure in a shared library. 

Synopsis 

signed32 
gk_site_Init ( 

char *SitePolicyPathNameP ); /* IN */ 


Description 

This function is written by the customer site. It will be called by the Gatekeeper’s internal initialization 
routine whenever the Gatekeeper initializes or reinitializes. 

Parameters 

SitePolicyPathNameP A pointer to the path name of the file where the site policy is stored. This path 
name is defined to beHPSS MAX PATH NAME bytes long which is 1024 
bytes. 

Return Values 

Upon successful completion, a value of zero (0) is returned. Non-zero values are described in the Error 
Conditions. 

Error Conditions 

The gk_site_Init routine is unsuccessful if any of the following are true: 

HPSS EAGAIN Resources are temporarily unavailable. 

See Also 

None. 

Clients 

Gatekeeper. 

Notes 
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If an error value is returned, the Gatekeeper Server will not initialize. 

Example Usage 

Initialize mutex locks, global variables, etc. 

If the passed in SitePolicyPathNameP is non null and not nil, then 
Read the site policy file looking for things like: 

- The types of requests we're monitoring (authorized caller, creates, 
opens, stages) 

- Pathname to a log file. 

- Maximum size of the log file. 

- Debug settings. 

- Pathname to a dump file. 

- Maximum number of creates per host. 

- Maximum number of creates per user. 

- Maximum number of opens per host. 

- Maximum number of opens per user. 

- Maximum number of stages per host. (Note: Needs to be greater than 
the maximum number of opens per host.) 

- Maximum number of stages per user. (Note: Needs to be greater than 
the maximum number of opens per user.) 

Open and initialize the logfile (if one is configured). 

Log exit of this routine to the Site Policy Logfile. 

Return status. 

4.1.7. gk_site_Open 

Purpose 

This is an internal, site defined-and-implemented function that implements site policies which decide if a 
caller is authorized to open the file now, later, or not at all. This function is not an RPC. It is a call to a 
procedure in a shared library. 

Synopsis 

signed32 
gk_site_Open ( 

gk_EntryInfo_t Entrylnfo, /* IN */ 

unsigned32 *WaitTimeP) ; /* OUT */ 

Description 
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This function is written by the customer site. It is called by gk_Open whenever an HPSS file open occurs. 

Parameters 

Entrylnfo Information about the file being opened. 

WaitTimeP A pointer to the number of seconds to wait before retrying a request. 

Return Values 

Upon successful completion, a value of zero (0) is returned which tells the Gatekeeper to continue with the 

open request. After the Gatekeeper has returned success to the caller, it expects gk_site_Close to be called 

when the file has been closed or if an error occurred 

All non-zero return values will be treated as errors, thus the client will do the appropriate error handling and 

terminate the open request. Non-zero error values are described in the Error Conditions. 

Error Conditions 

The gk_site_Open routine is unsuccessful if any of the following are true: 

HPSSEACCES Permission is denied. 

HPSS EAGAIN Resources are temporarily unavailable. 

HPSS ENOTREADY Initialization has not completed. 

HPSS EPERM The operation is not permitted. 

HPSSERETRY The operation should be retried after the delay, in seconds, returned by 

the WaitTimeP parameter. 

HPSS ETHRESHOLD DENY This error code is returned to deny access due to exceeding athreshold. 

The Core Server will return this error to the Client API. The Client 
API will map this error into EBUSY before returning the error code to 
the application. 

HPSS EUSER DENY This error code is returned to deny access to a particular user. The 

Core Server will return this error to the Client API. The Client API 
will map this error into EACCESS before returning the error code to 
the application. 


See Also 


gk Close, gk Open, gk site Close, and gk site OpenStats. 

Clients 

Gatekeeper. 

Notes 


Routine gk_site_OpenStats is called instead of gk_site_Open whenever an HPSS file open occurs from an 
authorized caller when authorized caller requests are monitored. 

If the operation should be retried, HPSS RETRY is returned and the number of seconds the caller should 
wait before retrying is returned in the WaitTimeP parameter. If the site does not specify the WaitTimeP 
parameter (returns 0), the default value from the Gatekeeper’s specific configuration field DefaultWaitTime 
is used instead. 
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Example Usage 

Please see section gk_site_Create. 

4.1.8. gk_site_OpenStats 

Purpose 

This is an internal, site defined-and-implemented function that is called asynchronously by the Gatekeeper 
when an authorized caller is opening a file. It is only called when authorized caller requests and open 
requests are being monitored. This function is not an RPC. It is a call to a procedure in a shared library. 

Synopsis 

void 

gk_site_OpenStats ( 

gk_Entry!nfo_t Entrylnfo) ; /* IN */ 


Description 

This function is written by the customer site. It is called by gk_Open whenever an HPSS file open occurs 
from an authorized caller when both open requests and authorized caller requests are monitored. 

Parameters 

Entrylnfo Information about the file being opened. 


Return Values 

None. 

Error Conditions 

None. 


See Also 


gk Close, gk Open, gk site Close, and gk site Open. 

Clients 

Gatekeeper. 

Notes 


Routine gk_site_OpenStats is called instead of gk_site_Open whenever an HPSS file open occurs from an 
authorized caller when authorized caller requests are monitored. 

The Gatekeeper will queue all asynchronous calls to the site interfaces so that they are processed in the 
order they are received. For example, if a site is monitoring authorized caller, create and open requests and 
an authorized caller create request is issued before an authorized caller open request, then the Gatekeeper 
will queue these requests so that gk_site_CreateStats is called before gk_site_OpenStats. 

Example Usage 

Please see section gk_site_CreateStats. 
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4.1.9. gk_site_PassThru 

Purpose 

This is an internal, site defined-and-implemented function that is called by the Gatekeeper to pass 
information to the site interface. This function is not an RPC. It is a call to a procedure in a shared library. 

Synopsis 

signed32 

gk_site_PassThru ( 

u_signed64 Param64, /* IN */ 

unsigned char *ParamStr±ng) ; /* IN */ 

Description 

This function is written by the customer site. It will be used to pass information into the site interface. The 
site interface can define what these parameters mean. 

This function will be called by gk_PassThru. 

Parameters 

Param64 A 64 bit parameter. 

ParamString NULL-terminated string parameter. 

Return Values 

Upon successful completion, a value of zero (0) is returned. Non-zero values are described in the Error 
Conditions. 

Error Conditions 

The gk_site_PassThru routine is unsuccessful if any of the following are true: 

HPSSEAGAIN Resources are temporarily unavailable. 

HPSS ENOTREADY Initialization has not completed. 


See Also 


gkPassThru. 

Clients 

Gatekeeper. 

Notes 


The site may want to define bits in Param64 to correspond to special site actions. The ParamString may be 
used in conjunction with a bit(s) in Param64 or for some other use. For example, if bit position 0 is ON in 
Param64 then dump the current state to some file name passed in ParamString. The site will need to write 
its own client to use this interface (i.e. Core Server and SSM will not use this interface). 

Example Usage 

Log entrance of this routine to the Site Policy Logfile. 

If Param64 is zero, then 
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Log exit of this routine to the Site Policy Logfile. 

Return status. 

Verify bits passed into Param64 are valid options. 

If an unsupported bit is set in Param64, then 
Log an exit error to the Site Policy Logfile. 

Return status. 

If turned on the Dump State bit, then 
If ParamString is null or nil, then 

Dump the state of each cache and all the other good information into 
the dump file. 

Else 

Dump the state of each cache and all the other good information into 
the pathname stored in ParamString. 

Log exit of this routine to the Site Policy Logfile. 

Return status. 

4.1.10. gk_site_ReadSitePolicy 

Purpose 

This is an internal, site defined-and-implemented function that is called by the Gatekeeper to inform the site 
interface that the site policy file needs to be read. This function is not an RPC. It is a call to a procedure in 
a shared library. 

Synopsis 

signed32 

gk_site_ReadSitePolicy (void); 

Description 

This function is written by the customer site. It will be used to inform the site interface that the site policy 
file has been modified. This will allow the site interface to re-read the site policy file, if defined, and 
enforce the new policy. 

If the monitoring types are changed, the Gatekeeper and Core Server will need to be restarted in order for 
the Core Server to leam about it. Therefore, ignore changes in monitor type policy. 

This function will be called by gk_ReadSitePolicy. 

Parameters 

None. 

Return Values 

Upon successful completion, a value of zero (0) is returned. Non-zero values are described in the Error 
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Conditions. 


Error Conditions 

The gk_site_ReadSitePolicy routine is unsuccessful if any of the following are true: 

HPSSEAGAIN Resources are temporarily unavailable. 

HPSSENOTREADY Initialization has not completed. 

See Also 

gk ReadSitePolicy, and gk GetMonitorTypes. 

Clients 

Gatekeeper. 

Notes 

If the monitoring types are changed, the Gatekeeper and Core Server will need to be restarted in order for 
the Core Server to learn about it. Therefore, ignore changes in monitor type policy. 

Example Usage 

Log entrance of this routine to the Site Policy Logfile. 

If a site policy file exists, then 
Read the site policy file looking for things like: 

- The types of requests we're monitoring (authorized caller, creates, 
opens, stages) 

- Pathname to a log file. 

- Maximum size of the log file. 

- Debug settings. 

- Pathname to a dump file. 

- Maximum number of creates per host. 

- Maximum number of creates per user. 

- Maximum number of opens per host. 

- Maximum number of opens per user. 

- Maximum number of stages per host. (Note: Needs to be greater than 
the maximum number of opens per host.) 

- Maximum number of stages per user. (Note: Needs to be greater than 
the maximum number of opens per user.) 

Close the logfile (if one is already opened). 

Open the possibly new logfile (if one is configured). 
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Log exit of this routine to the Site Policy Logfile. 
Return status. 


4.1.11. gk_site_Shutdown 

Purpose 

This is an internal, site defined-and-implemented function that is called when the Gatekeeper is shutdown. 
This function is used to do whatever shutdown and cleanup is needed by the site module. This function is 
not an RPC. It is a call to a procedure in a shared library. 

Synopsis 

signed32 

gk_site_Shutdown (void); 

Description 

This function is written by the customer site. It will be called by the Gatekeeper’s internal shutdown routine 
whenever the Gatekeeper is issued a shutdown request. 

Parameters 

None. 

Return Values 

Upon successful completion, a value of zero (0) is returned. Non-zero values are described in the Error 
Conditions. 

Error Conditions 

The gk_site_Shutdown routine is unsuccessful if any of the following are true: 

HPSS EAGAIN Resources are temporarily unavailable. 


See Also 


None. 

Clients 

Gatekeeper. 

Notes 

The Gatekeeper Server will not call this routine if it is issued a halt request or is crashing due to some 
critical problem. 

Example Usage 

Log entrance of this routine to the Site Policy Logfile. 

Flush and close the logfile, if one is already opened. 

Return status. 
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4.1.12. gk_site_Stage 

Purpose 

This is an internal, site defined-and-implemented function that implements site policies which decide if a 
caller is authorized to stage the file now, later, or not at all. This function not an RPC. It is a call to a 
procedure in a shared library. 

Synopsis 

signed32 
gk_site_Stage ( 

gk_EntryInfo_t Entrylnfo, /* IN */ 

unsigned32 *Wa±tT±meP) ; /* OUT */ 


Description 

This function is written by the customer site. It is called by gk_Stage whenever an HPSS file stage occurs. 

Parameters 

Entrylnfo Information about the file being staged. 

WaitTimeP A pointer to the number of seconds to wait before retrying a request. 

Return Values 

Upon successful completion, a value of zero (0) is returned which tells the Gatekeeper to continue with the 

stage request. After the Gatekeeper has returned success to the caller, it expects gk_site_StageComplete to 

be called when the file has been staged or if an error occurred. 

All non-zero return values will be treated as errors, thus the client will do the appropriate error handling and 

terminate the stage request. Non-zero error values are described in the Error Conditions. 

Error Conditions 

The gk_site_Stage routine is unsuccessful if any of the following are true: 

HPSSEACCES Permission is denied. 

HPSS EAGAIN Resources are temporarily unavailable. 

HPSS ENOTREADY Initialization has not completed. 

HPSS EPERM The operation is not permitted. 

HPSS ERETRY The operation should be retried after the delay, in seconds, returned by 

the WaitTimeP parameter. 

HPSS ETHRESHOLD DENY This error code is returned to deny access due to exceeding a 

threshold. The Core Server will return this error to the Client API. The 
Client API will map this error into EBUSY before returning the error 
code to the application. 

HPSS EUSER DENY This error code is returned to deny access to a particular user. The 

Core Server will return this error to the Client API. The Client API 
will map this error into EACCESS before returning the error code to 
the application. 
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gksiteStageComplete, gksiteStageStats, gkStage, and gkStageComplete. 


Clients 

Gatekeeper. 

Notes 


Routine gk_site_StageStats is called instead of gk_site_Stage whenever an HPSS file stage occurs from an 
authorized caller when authorized caller requests are monitored. 

If the operation should be retried, HPSSRETRY is returned and the number of seconds the caller should 
wait before retrying is returned in the WaitTimeP parameter. If the site does not specify the WaitTimeP 
parameter (returns 0), the default value from the Gatekeeper’s specific configuration field DefaultWaitTime 
is used instead. 

Example Usage 

Please see section gk_site_Create. 

4.1.13. gk_site_StageComplete 

Purpose 

This is an internal, site defined-and-implemented function that is called by the Gatekeeper when a file stage 
has completed. This function is not an RPC. It is a call to a procedure in a shared library. 

Synopsis 

signed32 

gk_site_StageComplete ( 

hpss_uuid_t ControlNo) ; /* IN */ 


Description 

This function is written by the customer site. It will be called by gk_StageComplete while processing a file 
stage completion of an HPSS file. 

Parameters 


ControlNo Unique identifier for the staged file which is now being completed. This 

number was generated by the Gatekeeper and passed into gk_site_Stage or 
gksiteStageStats. 


Return Values 

Upon successful completion, a value of zero (0) is returned. Non-zero values are described in the Error 
Conditions. 

Error Conditions 

The gk_site_StageComplete routine is unsuccessful if any of the following are true: 

HPSSEAGAIN Resources are temporarily unavailable. 

HPSS ENOENT Could not find an entry matching the ControlNo field in Entrylnfo. 

HPSS ENOTREADY Initialization has not completed. 
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See Also 


gksiteStage, gksiteStageStats, gkStage, and gkStageComplete. 

Clients 

Gatekeeper. 

Notes 

None. 

Example Usage 

Please see section gk_site_Close. 

4.1.14. gk_site_StageStats 

Purpose 

This is an internal, site defined-and-implemented function that is called asynchronously by the Gatekeeper 
when an authorized caller is staging a file. It is only called when authorized caller requests and stage 
requests are being monitored. This function is not an RPC. It is a call to a procedure in a shared library. 

Synopsis 

void 

gk_site_StageStats ( 

gk_EntryInfo_t Entrylnfo) ; /* IN */ 

Description 

This function is written by the customer site. It is called by gk_Stage whenever an HPSS file stage occurs 
from an authorized caller when both stage requests and authorized caller requests are monitored. 

Parameters 

Entrylnfo Information about the file being staged. 

Return Values 

None. 

Error Conditions 

None. 

See Also 

gk site Stage, gk site StageComplete, gkStage, and gk StageComplete. 

Clients 

Gatekeeper. 

Notes 

Routine gk_site_StageStats is called instead of gk_site_Stage whenever an HPSS file stage occurs from an 
authorized caller when authorized caller requests are monitored. 
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The Gatekeeper will queue all asynchronous calls to the site interfaces so that they are processed in the 
order they are received. For example, if a site is monitoring authorized caller, create and open requests and 
an authorized caller create request is issued before an authorized caller open request, then the Gatekeeper 
will queue these requests so that gk_site_CreateStats is called before gk_site_OpenStats. 

Example Usage 

Please see section gk_site_CreateStats. 

4.2. Account Validation Site Interface 

This section describes the site customizable parts of the Account Validation APIs. These routines are stored in a 
shared library to ease customization. 


4.2.1. av_site_AcctldxToName 

Purpose 

Customizable routine to convert an account index to an account name. 


Synopsis 


signed32 

av_site_AcctIdxToName( 

hpss_connect_handle_t 

hps s_reqid_t 

unsigned32 

unsigned32 

unsigned32 

unsigned32 

acct_rec_t 

char 

unsigned32 

) ; 


Binding, 

Requestld, 

Realmld, 

Uid, 

Gid, 

Flags, 

Acct, 

*AcctName, 
*OkToCache 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 
/* OUT */ 


Description 

This site customizable routine converts from an account index to an account name. By default, this routine 
is nothing more than a skeleton that returns HPSSEUSEDEFAULT immediately. 

Parameters 


Binding 

Binding handle to this server. 

Requestld 

Request identifier to use when logging messages for this request. 

Realmld 

Realm identifier of this account. 

Uid 

User id (UID) of user. 

Gid 

Group id (GID) of user. 

Flags 

May be zero or more of the following OR’d together: 

ACCT FLAGS VALID INDEX - Verify that the specified user is 
allowed to use this account index. 

Acct 

Account Index to translate. 
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AcctName 

OkToCache 


Pointer to returned account name. 


True if Account Validation Library should cache the result. See Notes for 
more information. 

Return Values 

Upon successful completion, zero (0) is returned. A non-zero value indicates an error condition. 

Error Conditions 


HPSSEUSEDEFAULT Tells the caller to use the default built-in behavior for this routine. 
Other suggested error codes to use are: 


HPSSEBUSY 

HPSSENOENT 

HPSSEPERM 

HPSSESYSTEM 


See Also 


avAcctldxT oN ame 

Clients 

Client API via Gatekeeper 

Notes 


The server is busy. The request should be retried later. 

The account in Acct does not exist. AcctName is set to the string form of 
Acct. If ACCTFLAGSVALIDINDEX is set in the Flags parameter, 
you should return HPSS EPERM instead. 

The specified user is not allowed to use that account index. 

This routine received an internal error. Usually a site customization 
problem. 


This routine can be customized by a site. It is the site’s responsibility to make sure that consistent results 
are returned and performance is not adversely impacted. 

The OkToCache argument should normally be TRUE. If a site customizes this routine it should only set 
this argument to FALSE if the returned information can change over time and should not be cached by the 
client. 

Example Usage 

This example is the default behavior of the av_AcctIdxToName routine. See the implementation of that 
routine, if available, for more details. 

av AcctldxToNameO { 

if site style accounting { 

if Acct == ACCTRECDEFAULT 
lookup user default acct; 
else lookup account Acct; 

if (not found) { 

if Flags & ACCT FLAGS VALID INDEX 
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error = HPSS_EPERM; 


else error = HPSS ENOENT; 

} 

else if (unix style accounting) 

if (Acct = ACCT REC DEFAULT) Acct = Uid; 
if (Acct != Uid && Flags & ACCTFLAGSVALIDINDEX) 
error = HPSS_EPERM; 

else { 

convert Realm,Acct into name 

if not found && Flags & ACCT FLAGS VALID INDEX 
error = HPSS_EPERM; 

} 

} 

return error; 


4.2.2. av_site_AcctNameToldx 

Purpose 

Customizable routine to convert an account name to an account index 

Synopsis 


signed32 

av_site_AcctNameToIdx( 


hpss_connect_handle_t 

Binding, 

/* IN */ 

hpss_reqid_t 

Requestld, 

/* IN */ 

unsigned32 

Realmld, 

/* IN */ 

unsigned32 

Uid, 

/* IN */ 

unsigned32 

Gid, 

/* IN */ 

unsigned32 

Flags, 

/* IN */ 

char 

* InAcctName, 

/* IN */ 

char 

*Ou tAcctName, 

/* OUT *, 

acct_rec_t 

*Acct, 

/* OUT *, 

unsigned32 

*OkToCache 

/* OUT *> 


) ; 


Description 

This site customizable routine converts from an account name to an account index. By default, this routine 
is nothing more than a skeleton that returns HPSS EUSEDEFAULT immediately. 

Parameters 
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Binding 

Requestld 

Realmld 

Uid 

Gid 

Flags 


InAcctName 


OutAcctName 


Acct 


Binding handle to this server. 

Request Id to use when logging messages for this request. 

Realm identifier of user. 

User id (UID) of user. 

Group id (GID) of user. 

May be zero or more of the following OR’d together: 

ACCTFLAGSVALIDINDEX - Verify that the specified user is 
allowed to use this account index. 

Optional pointer to account name to translate. If this argument is NULL or 
points to an empty string, information about the user’s default account 
index is returned. 

Optional pointer to returned account name. The name of the user’s default 
account is returned if the InAcctName parameter is NULL or points to an 
empty string. Otherwise, the value of InAcctName is returned. Note that 
the name of the default account for UNIX Style accounting is the empty 
string. 

Pointer to the returned account index. 


OkToCache 


True if Account Validation Library should cache the result. See Notes for 
more information. 


Return Values 

Upon successful completion, zero (0) is returned. A non-zero value indicates an error condition. 

Error Conditions 

HPSS EUSEDEFAULT Tells the caller to use the default built-in behavior for this routine. 

Other suggested error codes to use are: 

HPSSEBUSY 
HPSSENOENT 

HPSSEPERM 
HPSSESYSTEM 

See Also 

avAcctNameToIdx 

Clients 

Client API via Gatekeeper 

Notes 

This routine can be customized by a site. It is the site’s responsibility to make sure that consistent results 


The server is busy. The request should be retried later. 

The account specified does not exist. Acct is set to the integer form of 
AcctName. If ACCT FLAGS VALID INDEX is set in the Flags 
parameter, then return HPSS EPERM instead. 

The specified user is not allowed to use that account name. 

This routine received an internal error. Usually a site customization 
problem. 
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are returned and performance is not adversely impacted. 


The OkToCache argument should normally be TRUE. If a site customizes this routine it should only set 
this argument to FALSE if the returned information can change over time and should not be cached by the 
client. 

Example Usage 

This example is the default behavior of av_AcctNameToIdx. See the implementation of that routine, if 
available, for more details. 

av_AcctNameToIdx() { 

lookupdefault = (InAcctName is NULL or empty); 
if site style accounting { 
if lookup default 

read default account for this user from metadata 
if (not found and requiring default account) 
return HPSS_EPERM; 

else if Flags & ACCT FLAGS VALID INDEX 
read this user’s account by name 

else 

read account metadata by name 
} else if unix style accounting { 
if (lookup default) 

*Acct = Uid; 

else { 

try to convert AcctName to number 
if successful, *Acct = number; 

} 

} 


if we set *Acct above { 

error = lookup user from uid 
if not found and require default account 
error = HPSS_EPERM; 

} else { 

error = lookup user from account name 
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if (not found and Flags & ACCT FLAGS VALID INDEX 
error = HPSS_EPERM; 


return error; 


4.2.3. av_site_lnitialize 

Purpose 

Customizable routine to perform initialization of the Account Validation APIs. 

Synopsis 

signed32 

av_site_Initialize( 

acct_config_t *AcctPolicy /* IN */ 

) ; 

Description 

This routine initializes the site customized APIs which receive client requests. Sites should initialize any 
common state shared between the various site routines. 

Parameters 

AcctPolicy Pointer to accounting policy metadata record. 

Return Values 

Upon successful completion, zero (0) is returned. A non-zero value indicates an error condition. 

Error Conditions 

Suggested error codes to use: 

HPSSSYSTEM 
HPSSENOMEM 

See Also 

avlnitialize 

Clients 

Gatekeeper 

Notes 

This routine can be customized by a site. It is the site’s responsibility to make sure that consistent results 
are returned and performance is not adversely impacted. Any error returned from this routine is considered 
fatal and will keep the server from starting up properly. 

Example Usage 


Site code cannot initialize properly. 
Out of memory. 
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av_site_Initialize() { 

allocate space for local site policy information; 
read in local site policy information; 


4.2.4. av_site_Shutdown 

Purpose 

Customizable routine to shutdown the interface to the Account Validation APIs. 

Synopsis 

signed32 

av_site_Shutdown(void); 

Description 

This routine cleans up any state created by the customizable site routines. 

Parameters 
None 
Return Values 

Upon successful completion, zero (0) is returned. A non-zero value indicates an error condition. 

Error Conditions 

Suggested error codes to use: 

HPSS EINVAL The APIs have not been initialized so there is nothing to shutdown. 

See Also 

None 

Clients 

Gatekeeper 

Notes 

This routine can be customized by a site. It is the site’s responsibility to make sure that consistent results 
are returned and performance is not adversely impacted. Any error returned from this routine is logged but 
otherwise ignored. 

Example Usage 

av_site_Shutdown() { 

deallocate space for local site policy information; 

} 
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4.2.5. av_site_ValidateAccount 

Purpose 

Customizable routine to validate that a user is allowed to use an account index. 


Synopsis 

signed32 

av_site_ValidateAccount( 

hpss connect handle t Binding, 


hpss_reqid_t 
unsigned32 
unsigned32 
acct_rec_t 
unsigned32 
acct_rec_t 
acct_rec_t 
unsigned32 
) ; 


Requestld, 

Realmld, 

Uid, 

Acct, 

Flags, 

*ParentAcct, 
*OutAcct, 
*OkToCache 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 
/* OUT */ 


Description 

This routine verifies that Acct is a valid account index to use for the user specified by the Uid and Realmld 
given. By default, this routine is nothing more than a skeleton that returns HPSSEUSEDEFAULT 
immediately. See av ValidateAccount for the default behavior of this routine. 

Parameters 


Binding 

Requestld 

Realmld 

Uid 

Acct 

Flags 


ParentAcct 

OutAcct 

OkToCache 


Binding handle to this server. 

Request Id to use when logging messages for this request. 

Realm identifier of user. 

User id (UID) of user. 

Account Index to validate. If this is ACCTRECDEFAULT, the 
specified user’s default account index, if any, is used instead. 

One or more of the following OR’d together: 

ACCT VALIDATE FLAGS CREATING - Caller is performing a file or 
directory creation operation. 

ACCT VALIDATE FLAGS AUTH CALLER - Request is being made 
on the behalf of an authorized caller. 

Pointer to parent account index. 

Account Index to use. 

True if Account Validation Library should cache the result. See Notes for 
more information. 


Return Values 


Upon successful completion, zero (0) is returned signifying that the account is valid. 
A non-zero value indicates an error condition. 
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Error Conditions 


HPSSEUSEDEFAULT Tells the caller to use the default built-in behavior for this routine. 

Other suggested error codes to use are: 

HPSS EBUSY The server is busy. The request should be retried later. 

HPSS EPERM The specified user is not allowed to use that account index. 

HPSS ESYSTEM This routine received an internal error. Usually a site customization 

problem. 

See Also 

av_V alidate Account 

Clients 

Core Server via Gatekeeper 

Notes 

This routine can be customized by a site. It is the site’s responsibility to make sure that consistent results 
are returned and performance is not adversely impacted. 

The OkToCache argument should normally be TRUE. If a site customizes this routine it should only set 
this argument to FALSE if the returned information can change over time and should not be cached by the 
client. 

If this request is being performed on the behalf of an authorized caller, it is generally not appropriate to 
return a permission error from this routine. See av_ValidateAccount. 

Example Usage 

This example is the default behavior of av_ValidateAccount. See the implementation of that routine, if 
available, for more details. 

av_ValidateAccount() { 

if site style and creating a file and account inheritance is on { 
if (parent account supplied and 

(Acct is ACCTRECDEFAULT or parent account)) { 
return with parent account; 

} else if (no parent account supplied and 

Acct != ACCT REC DEFAULT) { 

/* assume caller (Core Server) has determined parent already */ 
return with Acct; 


if (user is superuser) 
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return with Acct; 
if (user is “nobody”) { 
if auth caller 

return with ACCTRECDEFAULT 
return HPSS_EPERM; 

} 

if site style accounting { 

Read the account from metadata. 

If (not found and Acct = ACCT REC DEFAULT and auth caller) { 
Create default account for this user; 

} else if not found { 

error = HPSS_EPERM; 

} 

} else if unix style { 

if Acct == UID or ACCTRECDEFAULT or auth caller 
return with Uid; 
error = HPSS_EPERM; 

} 

return error; 


4.2.6. av_site_ValidateChacct 

Purpose 

Determine the account code to use when a file’s account index changes. 

Synopsis 

signed32 

av_site_ValidateChacct 
hpss_connect_handle_t 
hps s_reqid_t 
unsigned32 
unsigned32 
unsigned32 
unsigned32 
unsigned32 
acct_rec_t 
acct_rec_t 
acct rec t 


Binding, 
Requestld, 
UserRealmld, 
UserUid, 
FileRealmld, 
FileUid, 
FileGid, 
OldAcct, 
NewAcct, 
*OutAcct, 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 
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unsigned32 

) ; 


*OkToCache 


/* OUT */ 


Description 

This routine determines what account index should be used when a file or directory’s account index 
changes. By default, this routine is nothing more than a skeleton that returns HPSSEUSEDEFAULT 
immediately. See av_ValidateChacct for the default behavior of this routine. 

Parameters 


Binding 

Requestld 

UserRealmld 

UserUid 

FileRealmld 

FileUid 

FileGid 

OldAcct 

NewAcct 

OutAcct 

OkToCache 


Binding handle to this server. 

Request Id to use when logging messages for this request. 

Realm identifier of user performing the operation. 

User id (UID) of user performing the operation. 

Realm identifier of file’s owner. 

User id (UID) of file’s owner. 

Group id (GID) of file’s owner. 

Old Account Index of file. 

New Account Index to put onto the file. If this is ACCT REC DEFAULT 
then the user’s default account index is used. 

Returned account index to use. 

True if Account Validation Library should cache the result. See Notes for 
more information. 


Return Values 

Upon successful completion, zero (0) is returned. A non-zero value indicates an error condition. 

Error Conditions 

HPSS EUSEDEFAULT Tells the caller to use the default built-in behavior for this routine. 
Other suggested error codes to use are: 

HPSS EBUSY The server is busy. The request should be retried later. 

HPSS EPERM The account specified may not be used by this user. 

HPSS ESYSTEM This routine received an internal error. Usually a site customization 

problem. 

See Also 

avValidateChacct 

Clients 

Client API via Gatekeeper 

Notes 
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This routine can be customized by a site. It is the site’s responsibility to make sure that consistent results 
are returned and performance is not adversely impacted. 

The OkToCache argument should normally be TRUE. If a site customizes this routine it should only set 
this argument to FALSE if the returned information can change over time and should not be cached by the 
client. 

Example Usage 

This example is the default behavior of av_ValidateChacct. See the implementation of that routine, if 
available, for more details. 

av_ValidateChacct() { 

if user is “nobody”, return with *OutAcct = ACCTRECDEFAULT; 
if site style accounting { 

if user is superuser and Acct != ACCTRECDEFAULT 
return with New Acct; 
error = read user account from metadata 
if not found { 

if NewAcct = ACCT REC DEFAULT, return 0 
else return HPSS EPERM; 

} 

} else if unix style accounting { 

if NewAcct is FileUid or ACCTRECDEFAULT 
return with *OutAcct = FileUid; 
error = HPSS_EPERM; 

} 

return error; 

} 

4.2.7. av_site_ValidateChown 

Purpose 

Determine the account code to use when a file’s ownership or group changes. 

Synopsis 

signed32 

av_site_ValidateChown( 

hpss_connect_handle_t Binding, /* IN */ 

hps s_reqid_t Requestld, /* IN */ 

unsigned32 OldRealmld, /* IN */ 

unsigned32 OldUid, /* IN */ 
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unsigned32 

OldGid, 

/* IN */ 

acct_rec_t 

OldAcct, 

/* IN */ 

unsigned32 

NewRealmld, 

/* IN */ 

unsigned32 

NewUid, 

/* IN */ 

unsigned32 

NewGid, 

/* IN */ 

acct_rec_t 

SessionAcct, 

/* IN */ 

acct_rec_t 

*OutAcct, 

/* OUT *, 

unsigned32 
) ; 

*OkToCache 

/* OUT *, 

Description 




This routine determines what account index should be used when a file or directory’s ownership changes or 
its group changes. By default, this routine is nothing more than a skeleton that returns 
HPSSEUSEDEFAULT immediately. See av_ValidateChown for the default behavior of this routine. 

Parameters 


Binding 

Requestld 

OldRealmld 

OldUid 

OldGid 

OldAcct 

NewRealmld 

NewUid 

NewGid 

SessionAcct 

OutAcct 

OkToCache 


Binding handle to this server. 

Request Id to use when logging messages for this request. 

Realm identifier of file’s owner. 

User id (UID) of file’s owner. 

Group id (GID) of fde. 

Account Index of file. 

New Realm identifier of file’s owner. 

New User id (UID) of file’s owner. 

New Group id (GID) of fde. 

User’s current session account index. 

Returned account index to use. 

True if Account Validation Library should cache the result. See Notes for 
more information. 


Return Values 

Upon successful completion, zero (0) is returned. A non-zero value indicates an error condition. 

Error Conditions 

HPSS EUSEDEFAULT Tells the caller to use the default built-in behavior for this routine. 
Other suggested error codes to use are: 


HPSSEBUSY 

HPSSEPERM 

HPSSESYSTEM 


See Also 


The server is busy. The request should be retried later. 

The account specified may not be used by this user. 

This routine received an internal error. Usually a site customization 
problem. 
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avsiteV alidateChown 

Clients 

Client API via Gatekeeper 

Notes 

This routine can be customized by a site. It is the site’s responsibility to make sure that consistent results 
are returned and performance is not adversely impacted. 

The OkToCache argument should normally be TRUE. If a site customizes this routine it should only set 
this argument to FALSE if the returned information can change over time and should not be cached by the 
client. 

Example Usage 

This example is the default behavior of av_ValidateChown. See the implementation of that routine, if 
available, for more details. 

av_ValidateChown() { 

if user is “nobody”, return with *OutAcct = ACCT REC DEFAULT; 
if site style accounting { 

error = read user account from metadata 
if not found { 

error = 0; 

*OutAcct = ACCTRECDEFAULT; 

} 

} else if unix style accounting { 

*OutAcct = NewUid; 

} 

return error; 


4.2.8. av_site_ValidateCreate 

Purpose 

Customizable routine to determine the account code to use when creating a file or directory. 

Synopsis 

signed32 

av_site_ValidateCreate ( 
hpss_connect_handle_t Binding, 
hpss_reqid_t Requestld 

unsigned32 Realmld, 


/* IN */ 
/* IN */ 
/* IN */ 
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unsigned32 
unsigned32 
acct_rec_t 
acct_rec_t 
acct_rec_t 
unsigned32 
) ; 


Uid, 

Gid, 

Acct, 

ParentAcct, 

*OutAcct, 

*OkToCache 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 
/* OUT */ 


Description 

This routine determines what account index should be used when a file or directory is created. By default, 
this routine is nothing more than a skeleton that returns HPSSEUSEDEFAULT immediately. See 
av_ValidateCreate for the default behavior of this routine. 

Parameters 


Binding 

Requestld 

Realmld 

Uid 

Gid 

Acct 

ParentAcct 

OutAcct 

OkToCache 


Binding handle to this server. 

Request Id to use when logging messages for this request. 

Realm identifier of new file’s owner. 

User id (UID) of new file’s owner. 

Group id (GID) of new file. 

Current session account index. 

Account Index of parent directory. 

Returned account index to use. 

True if Account Validation Library should cache the result. See Notes for 
more information. 


Return Values 

Upon successful completion, zero (0) is returned. A non-zero value indicates an error condition. 

Error Conditions 

HPSS EUSEDEFAULT Tells the caller to use the default built-in behavior for this routine. 
Other suggested error codes to use are: 

HPSS EBUSY The server is busy. The request should be retried later. 

HPSS EPERM The account specified may not be used by this user. 

HPSS ESYSTEM This routine received an internal error. Usually a site customization 

problem. 

See Also 

avValidateCreate 

Clients 

Client API via Gatekeeper 

Notes 
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This routine can be customized by a site. It is the site’s responsibility to make sure that consistent results 
are returned and performance is not adversely impacted. 


The OkToCache argument should normally be TRUE. If a site customizes this routine it should only set 
this argument to FALSE if the returned information can change over time and should not be cached by the 
client. 

Example Usage 

This example is the default behavior of av_ValidateCreate. See the implementation of that routine, if 
available, for more details. 

av_ValidateCreate() { 

if site style accounting and account inheritance and 
parent account is supplied { 
return with parent account; 

} 

if user is “nobody”, return with ACCTRECDEFAULT; 
if site style accounting { 

if (user is superuser and Acct != ACCT REC DEFAULT) 
return ok with OutAcct = Acct; 
error = read user account from metadata; 
if not found { 

if Acct = ACCT REC DEFAULT, return with OutAcct = Acct; 
else return with HPSS EPERM; 

} 

} else if unix style accounting { 

* OutAcct = Uid; 

} 

log any error; 
return error; 
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Chapter 5. Access Control List API Functions 


5.1. API Interfaces 

This chapter describes all the APIs that are provided in shared object hacl.so which is included in the HPSS Client 
Library libhpss.a. In this discussion, the term "object" is used to refer to files and directories. The API interface 
specification includes the following information: 

• Name 

• Purpose 

• Synopsis 

• Description 

• Parameters 

• Return Values 

• Error Conditions 

• See Also 

• Notes 

5.1.1. hacl_ConvertACLToHACL 

Purpose 

Convert an access control list to string format. 

Synopsis 

#include "hacl.h" 
int 

hacl_ConvertACLToHACL( 
ns_ACLConfArray_t *ACL_n, 

hacl_acl_t **ACL_h) 

Description 

Convert an access control list from the format used by the Client API routines into a format suitable for 
printing or use by other had routines. 

Parameters 

ACLn The ACL to be converted 

ACL h The converted ACL 

Return Values 

If successful, returns zero. Otherwise, returns one of the values described below. 

Error Conditions 

EINVAL ACL n was not a valid nameserver ACL 


/* IN */ 
/* OUT */ 
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ENOMEM Not enough memory available for conversion 

(other) An error returned by hpss_ConvertNamesToIds 

See Also 

haclConvertH ACLT o ACL 

Notes 

When ACLh is no longer needed, the memory assigned to it must be returned by calling ffee(). 

5.1.2. hacl_ConvertHACLToACL 

Purpose 

Convert an access control list to HPSS format. 

Synopsis 

#include "had. h" 
int 

had_ConvertHACLToACL ( 

had_ad_t *ACL_h, /* IN */ 

ns_ACLConfArray_t **ACL_n) /* OUT */ 

Description 

Convert an access control list into a format suitable for use with the Client API functions that manage 
access control lists. 

Parameters 

ACLh The ACL to be converted 

ACLn The converted ACL 

Return Values 

If successful, returns zero. Otherwise, returns one of the values described below. 

Error Conditions 

EINVAL ACL h was not a valid access control list 

ENOMEM Not enough memory available for conversion 

(other) Error returned by hpss ConvertNamesToIds 

See Also 

haclConvertACLT oH ACL 

Notes 

When ACL n is no longer needed, the memory assigned to it must be returned by calling free(). 

5.1.3. hacl_ConvertHACLToString 

Purpose 
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Convert an access control list to a form suitable for printing 

Synopsis 

#include "hacl.h" 
int 

hacl_ConvertHACLToString( 
hacl_acl_t *ACL_h, 

int Flags, 

char *EntrySeparator, 

char **ACL_s); 

Description 

Convert an access control list into a form suitable for printing. 

Parameters 

ACLh The ACL to be converted 

Flags Flags that define how output is to be formatted 

EntrySeparator String to be used to separate ACL entries 

ACLs The converted ACL 

Return Values 

If successful, returns zero. Otherwise, returns one of the values described below. 

Error Conditions 

ENOMEM Not enough memory available to hold ACL S 

EINVAL ACL h or EntrySeparator or ACL s is invalid 


/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 


See Also 


hpssConvertStringT oHACL 


Notes 


The Flags argument is the sum of values that determine how the ACL will be formatted. The following bits 
are defined: 

HACLMUSELOCALREALMSPEC 

HACLMUSEMASKOBJ 

If HACL M USE LOCAL REALM SPEC is set, the id of the local realm will be displayed in all ACL 
entries, even those that refer to principals in the local realm. Otherwise the realm will only be displayed for 
entries that refer to foreign principals. 

If HACL M USE MASK OBJ is set, the string will be adjusted to reflect the mask object. Otherwise the 
actual ACL will be shown. 

When ACL s is no longer needed, the memory assigned to it must be returned by calling free(). 
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5.1.4. hacl_ConvertHACLPermsToPerms 

Purpose 

Convert permission string to HPSS format 
Synopsis 

#include "had. h" 
int 

hacl_ConvertHACLPermsToPerms( 

char *HPerms, /* IN */ 

unsigned char *Perms); /* OUT */ 

Description 

Convert a permission string in the format "rwxcid" into a form suitable for use with the Client API ACL 
management functions. Both uppercase and lower case letters may be used, A hyphen may be used to indi¬ 
cate missing permission bits. 

Parameters 

HPerms The permissions to convert 

Perms The converted permissions 

Return Values 

If successful, returns zero. Otherwise, returns one of the values described below. 

Error Conditions 

EINVAL Hperms contained an unrecognized character 


See Also 


haclConvertPermsT oHACLPerms 

Notes 


None 

5.1.5. hacl_ConvertHACLTypeToType 

Purpose 

Convert access control list entry type to HPSS format 
Synopsis 

#include "hacl.h" 
int 

hacl_hacl_ConvertHACLTypeToType( 
char HType, /* IN */ 

unsigned char *Type); /* OUT */ 

Description 

Convert an ACL entry type into a form suitable for use with Client API functions. Valid type names 
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include any of the standard HPSS ACL entry types. These include userobj, groupobj, otherobj, user, 
group, foreign user, foreign group, foreign other, any other, mask obj, user obj delegate, 
group obj delegate, other obj delegate, foreign other delegate, and any other delegate. Strings can be 
entered in upper or lower case letters. The extended type is not allowed. The unauthorized type is allowed 
but most Client API routines will treat this ACL entry type as invalid. The output type will be a valid Core 
Server ACL type such as ACL OBJ MASK, etc. 

Parameters 

HType The type to convert 

Type The converted type 

Return Values 

If successful, returns zero. Otherwise, returns one of the values described below. 

Error Conditions 

EINVAL HType is not a valid ACL entry type 


See Also 


haclConvertTypeToHACLType 

Notes 


None 

5.1.6. hacl_ConvertPermsToHACLPerms 

Purpose 

Convert HPSS permission mask to string 

Synopsis 

#include "had. h" 
int 

had_ConvertPermsToHACLPerms ( 
unsigned char Perms, /* IN */ 

char *HPerms ); /* OUT */ 

Description 

Convert the permissions mask returned by hpss_GetACL into a form suitable for printing and/or input into 
other libhacl routines. The output takes the form of a string (e.g., "rwxcid") with missing permissions 
replaced by a hyphen (e.g., "rwx—"). 

Parameters 

Perms The permisions to convert 

HPerms The converted permissions 

Return Values 

If successful, returns zero. Otherwise, returns one of the values described below. 
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Error Conditions 


EINVAL Perms is not a valid permission mask 


See Also 


haclConvertHACLPermsT oPerms 

Notes 


None 

5.1.7. hacl_ConvertStringsToHACL 

Purpose 

Convert access control list strings to HACL format 

Synopsis 

#include "had. h" 
int 

had_ConvertStringsToHACL ( 

int NumEntries, /* IN */ 

char *Entries[], /* IN */ 

char *DefaultRealm, /* IN */ 

char *WhiteSpaceChars, /* IN */ 

int Flags, /* IN */ 

hacl_acl_t **ACL_h) ; /* OUT */ 


Description 

Convert one or more string representations of access control list entries into a structure for input to other 
libhacl functions. 

Parameters 


NumEntries 

Entries 

DefaultRealm 

WhiteSpaceChars 

Flags 


ACLh 


Number of elements in Entries 
Array of ACL strings 
Default Realm 
Entry separator(s) 

Flags 

Resulting ACL 


Return Values 

If successful, returns zero. Otherwise, returns one of the values described below. 

Error Conditions 


ENOMEM Cannot allocate memory for ACL 

EINVAL One or more ACL entries is in error 

ENAMETOOLONG The length of DefaultRealm exceeds a system-imposed limit 
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See Also 


haclConvertHACLToString 

Notes 


The Entries argument is an array of strings, each of which represents one or more ACL entries. If there are 
several ACLs in any one string, they are separated by the character(s) listed in WhiteSpace. The Flags 
argument defines the format of the incoming string. The following bits are defined: 

HACLMREQUIREPERMS 

HACLMUSELOCALREALMSPEC 

If HACL M REQUIRE PERMS is set, then the permission string must be supplied as part of the ACL 
entry. Otherwise, the permission string is optional. The first case would be used when an ACL is being 
created, while the second case would be used when an ACL entry is being deleted. 

If HACL M USE LOCAL REALM SPEC is set, the id of the local realm can optionally be provided in 
all ACL entries, even those that refer to principals in the local realm. Otherwise the realm should be 
specified only for entries that refer to foreign principals. 

When ACL h is no longer needed, the memory assigned to it must be returned using free(). 

5.1.8. hacl_ConvertTypeToHACLType 

Purpose 

Convert an access control list entry type to string format 

Synopsis 

#include "hacl.h" 
int 

hacl_ConvertTypeToHACLType( 
unsigned char Type, 
char *HType); 

Description 

Convert an ACL entry type into a form suitable for printing or use with other functions in libhacl. The input 
type should be a valid nameserver ACL type such as ACL OBJ MASK, etc. The output is the 
corresponding string (eg, "mask obj"). 

Parameters 

Type The entry type to convert 

HType The converted type 

Return Values 

If successful, returns zero. Otherwise, returns one of the values described below. 

Error Conditions 

EINVAL Type was not a valid ACL entry type 


/* IN */ 
/* OUT */ 


See Also 
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haclConvertHACLTypeToType 

Notes 

None 

5.1.9. hacl_DeleteHACL 

Purpose 

Delete selected entries from an object’s access control list 

Synopsis 

#include "hacl.h" 
int 

hacl_DeleteHACL( 

char *Path, /* IN */ 

unsigned32 Options, /* IN */ 

hacl_acl_t *ACL_h); /* IN */ 

Description 

Delete the access control list entries specified in ACLh from the file named by Path. The Options 
argument is used to select whether an initial container or initial object ACLs are to be processed. 

Parameters 

Path Path to the object 

Options Processing options 

ACL h ACL entries to be deleted 

Return Values 

If successful, returns zero. Otherwise, returns one of the values described below. 

Error Conditions 

EACCES Search permission is denied on a component in Path 

EFAULT The Path or ACL parameter is a NULL pointer 

EINVAL ACL h contains invalid data 

ENAMETOOLONG The length of Path exceeds a system-imposed limit 

ENOENT The named object does not exist, or Path is an empty string 

ENOTDIR A component of Path is not a directory 

EPERM No privilege for attempted operation 

ESRCH A specified ACL entry could not be found in the object’s existing ACL 

See Also 

haclGetHACL 

Notes 
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The Options flag determines processing options. Values include: 
HP S SACLOB JECTACL - regular ACL 
HPSS ACL INITIAL CONTAINERACL - initial container ACL 
HPSSACLINITIALOBJECTACL - initial object ACL 


5.1.10. hacl_GetHACL 

Purpose 

Get an object’s access control list 

Synopsis 

#include "had. h" 
int 

had_GetHACL ( 

char *Path, /* IN */ 

unsigned32 Options, /* IN */ 

hacl_acl_t **ACL_h ); /* OUT */ 

Description 

Get the access control list of a object. The Options argument is used to select whether an initial container 
or initial object ACL is to be obtained. 

Parameters 

Path Path to the object 

Options Processing options 

ACLJi The object’s access control list 

Return Values 

If successful, returns zero. Otherwise, returns one of the values described below. 

Error Conditions 


EACCES 

EFAULT 

EINVAL 

ENAMETOOLONG 

ENOENT 

ENOTDIR 

EPERM 


Search permission is denied on a component in Path 
The Path or ACL parameter is a NULL pointer 
Path or Acl h is invalid 

The length of Path exceeds a system-imposed limit 
The named object does not exist, or Path is an empty string 
A component of Path is not a directory 
No privilege for attempted operation 


See Also 


hacl SetHACL, hacl_DeleteHACL 


Notes 
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The Options flag determines processing options. Values include: 


HPSS ACL OBJECT ACL The Path or ACL parameter is a NULL pointer 

HPSS ACL INITIAL CONTAINER ACL Initial container ACL 
HPSS ACL INITIAL OBJECT ACL Initial object ACL 

When ACLh is no longer needed, the memory assigned to it must be returned by calling free(). 

5.1.11. hacl_SetHACL 

Purpose 

Replace an object’s access control list with a new one 

Synopsis 

#include "hacl.h" 
int 

hacl_SetHACL( 

char *Path, /* IN */ 

unsigned32 Options, /* IN */ 

hacl_acl_t *ACL_h); /* IN */ 

Description 

Replace the access control list of the object named by Path with a new one given by ACL h. The Options 
argument is used to select whether an initial container or initial object ACL are to be processed. 

Parameters 

Path Path to the object 

Options Processing options 

ACL h The new ACL 

Return Values 

If successful, returns zero. Otherwise, returns one of the values described below. 

Error Conditions 

EACCES Search permission is denied on a component in Path 

EFAULT The Path or ACL parameter is a NULL pointer 

EINVAL ACL h contains invalid data 

ENAMETOOLONG The length of Path exceeds a system-imposed limit 

ENOENT The named object does not exist, or Path is an empty string 

ENOTDIR A component of Path is not a directory 

EPERM No privilege for attempted operation 

See Also 

hacl GetHACL, hacl_DeleteHACL 
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Notes 


The Options flag determines processing options 
HPSSACLOBJECTACL 
HPSSACLINITIALCONTAINERACL 
HPSS_ACL_INITIAL_OBJECT_ACL 

5.1.12. hacl_SortHACL 

Purpose 

Sort an access control list into canonical order 

Synopsis 

#include "had. h" 
void 

had_SortHACL ( 
had_ad_t *ACL_h) ; /* IN/OUT */ 

Description 

Sort the entries of an access control list into a standard order. 

Parameters 

ACL h The ACL to be sorted 

Return Values 

None. 

Error Conditions 

None. The function always succeeds. 

See Also 

None 


Values include: 
Regular ACL 
Initial container ACL 
Initial object ACL 


Notes 


The "standard" order arranges ACL entries in the order that they will be considered to decide whether a 
principal has access to an object. Lor example, the maskobj will appear first, followed by the user obj, 
user, foreign user, etc. entries. If there are two entries of the same type, they will be sorted based on the 
EntryName and/or RealmName fields. 

This routine should be called before displaying an ACL using hacl ConvertHACLToString. 

5.1.13. haclJJpdateHACL 

Purpose 

Change selected entries in an object’s access control list 


HPSS Programmer's Reference 
Release 6.2 (Revision 2.0) 


July 2008 


293 



Synopsis 

#include "had. h" 
int 

hacl_UpdateHACL( 

char *Path, /* IN */ 

unsigned32 Options, /* IN */ 

hacl_acl_t *ACL_h); /* IN */ 

Description 

Update selected entries in an access control list of an object. The Options argument is used to select 
whether an initial container or initial object ACL is to be processed. 

Parameters 

Path Path to the object 

Options Processing options 

ACLh ACL to be updated 

Return Values 

If successful, returns zero. Otherwise, returns one of the values described below. 

Error Conditions 
EACCES 
EFAULT 
EINVAL 

ENAMETOOLONG 
ENOENT 
ENOTDIR 
EPERM 

See Also 

hacl DeleteACL, hacl 

Notes 

The Options flag determines processing options. Values include: 

HPS S ACL OB JEC T ACL Regular ACL 

HPSS ACL INITIAL CONTAINER ACL Initial container ACL 

HPSS ACL INITIAL OBJECT ACL Initial object ACL 

HPSSACLDONTCALCMASK Don’t calculate mask 

HPSS ACL CALC MASK IGNORE ERRORS Calculate mask unconditionally 


Search permission is denied on a component in Path 

The Path or ACL parameter is a NULL pointer 

ACL h contains invalid data 

The length of Path exceeds a system-imposed limit 

The named object does not exist, or Path is an empty string 

A component of Path is not a directory 

No privilege for attempted operation 

GetACL, hacl SetACL 
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5.2. Data Definitions 

This section describes the data definitions used by the routines in libhacl. 

5.2.1. HACL-style Access Control List - hacl_acl_t 

Description 

The Access Control List structure defines an array of ACL entries. 


Format 


typedef struct hacl_acl { 
size_t Length; 

char DefaultRealm[HPSS_MAX_REALM_NAME]; 

hacl_acl_entry_t ACLEntry[1]; 

} hacl_acl_t ; 

Length 

The number of ACL entries in array ACLEntry. 

DefaultRealm 

The realm used to set a context for interpreting the ACL. 

ACLEntry 

An array of ACL entries. 

5.2.2. HACL-style Access Control List Entry - hacl_acl_entry_t 

Description 

The Access Control List Entry structure defines one entry in an ACL. 


Format 


typedef struct hacl_acl_entry { 

char EntryType[HACL_MAX_TYPE]; 

char Perms[HACL_MAX_PERMS]; 

char EntryName[HPSS_MAX_PRINCIPAL_NAME]; 

char RealmName[HPSS_MAX_REALM_NAME]; 

} hacl_acl_entry_t; 

Entr yTy pe 

The type of ACL entry; e.g., "userobj", etc. 

Perms 

The permissions, composed of characters in "rwxcid-". 

EntryName 

Depending on the EntryType, the User name, group name, or realm name. 
RealmName 
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The realm name. Qualifies user and group names to make them unique. 
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Chapter 6. HPSS File System Client Interfaces 

This chapter describes the non-POSIX interfaces for the HPSS File System Client. The interfaces are in the form of 
ioctl(2) commands that can be used to control the HPSS specific properties for files being accessed via the File 
System Client interface. The interface specification includes the following information: 

• Name 

• Purpose 

• Synopsis 

• Description 

• Parameters 

• Return Values 

• Error Conditions 

• See Also 

• Clients 

• Notes 

• Example Usage 

6.1.1. HPSSFS_GET_COS 

Purpose 

Get the HPSS COS identifier for a file 
Synopsis 

#include Clinux/hpssfs.h> 

int 
ioctl( 

int fd, 

int cmd, 

unsigned int *cosid) 

Description 

This function is used to obtain the HPSS COS identifier for the open file, specified by the file descriptor,^. 

Parameters 

fd Open file descriptor 

cmd Command to execute (i.e. HPSSFS GET COS) 

cosid Pointer to the returned HPSS COS identifier for the file 

Return Values 

Upon successful completion, a value of zero (0) is returned. Non-zero values are described in the Error 
Conditions. 


/* IN - Open file descriptor */ 

/* IN - Command (HPSSFS_GET_COS) */ 
/* OUT - HPSS COS identifier */ 
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Error Conditions 

The ioctl(HPSSFS_GET_COS) routine is unsuccessful if any of the following are true: 

ENOTTY File descriptor is not associated with an HPSS file 

EFAULT Pointer value is invalid 

See Also 

HPSSFS_SET_COS_HINT 

Clients 

HPSS File System clients 

Notes 

None. 

Example Usage 

Open the HPSS file, with the open(2) system call. 

Issue the the HPSS GET COS ioctl(2) system call. 

6.1.2. HPSSFS_SET_COS_HINT 

Purpose 

Set the HPSS COS identifier hint for a file 
Synopsis 

#include 

int 
ioctl( 
int 
int 

unsigned 
Description 

This function is used to set the HPSS COS identifier hint for the open file, specified by the file descriptor, 
fd. Setting this hint, before any data is written to the file, allows HPSS to store file data in the corresponding 
HPSS COS. 

Parameters 

fd 

cmd 
cosid 

Return Values 

Upon successful completion, a value of zero (0) is returned. Non-zero values are described in the Error 
Conditions. 


Open file descriptor 

Command to execute (i.e. HPSSFS SET COS HINT) 
Pointer to the returned HPSS COS identifier for the file 


<linux/hpssfs.h> 


IN - Open file descriptor */ 

IN - Command (HPSSFS_SET_COS_HINT) */ 
IN - HPSS COS identifier */ 
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Error Conditions 

The ioctl(HPSSFS_SET_COS_HINT) routine is unsuccessful if any of the following are true: 

ENOTTY File descriptor is not associated with an HPSS file 

EFAULT Pointer value is invalid 

EBADF File descriptor was not obtained in write mode 

EPERM Data length for the file is not zero 

See Also 

HPSSFS SET FSIZE_HINT and HPSSFS_SET_MAXSEGSZ_HINT 

Clients 

HPSS File System clients 

Notes 

The file descriptor must be opened in write mode (i.e. OWRONLY or ORDWR). 

Example Usage 

Create the HPSS file, with the open(2) or create(2) system call. 

Issue the the HPSS SET COS HINT ioctl(2) system call. 

Write data to the file. 


6.1.3. HPSSFS_SET_FSIZE_HINT 

Purpose 

Set the HPSS file size hint for a file 
Synopsis 

#include <linux/hpssfs.h> 

int 
ioctl( 
int 
int 
off_t 

Description 

This function is uscu 10 sci me iitm 111c size min iui me open me, spceincu uy me 111c ucscupioi, ju. 
Setting this hint, before any data is written to the file, allows HPSS to select the segment size that best fits 
the specified file size. 

Parameters 

fd Open file descriptor 

cmd Command to execute (i.e. HPSSFS SET FSIZE HINT) 


/* IN - Open file descriptor */ 

/* IN - Command (HPSSFS_SET_FSIZE_HINT) */ 


/* IN - File size */ 
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Pointer to the size in bytes for the file 


Return Values 

Upon successful completion, a value of zero (0) is returned. Non-zero values are described in the Error 
Conditions. 

Error Conditions 

The ioctl(HPSSFS_SET_FSIZE_HINT) routine is unsuccessful if any of the following are true: 

ENOTTY File descriptor is not associated with an HPSS file 

EFAULT Pointer value is invalid 

EBADF File descriptor was not obtained in write mode 

EPERM Data length for the file is not zero 

See Also 

HPSSFS SET COS HINT and HPSSFS SET MAXSEGSZ HINT 

Clients 

HPSS File System clients 

Notes 

The file descriptor must be opened in write mode (i.e. OWRONLY or O RDWR). 

Example Usage 

Create the HPSS file, with the open(2) or create(2) system call. 

Issue the the HPSS SET FSIZE HINT ioctl(2) system call. 

Write data to the file. 


6.1.4. HPSSFS_SET_MAXSEGSZ_HINT 

Purpose 

Enable maximum segment size selection hint for a file 

Synopsis 

#include <linux/hpssfs.h> 

int 
ioctl( 

int fd, /* 

int cmd, /* 

off_t *setmax); /* 


IN - Open file descriptor */ 

IN - Command (HPSSFS_SET_MAXSEGSZ_HINT)*/ 
IN - Max segment enabler */ 


Description 

This function is used to enable maximum segment size selection hint for the open file, specified by the file 
descriptor,^. Setting this hint, before any data is written to the file, allows HPSS to select the maximum 
segment size value in the associated COS, for segment creation. 
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Parameters 


fd Open file descriptor 

and Command to execute (i.e. HPSSFS_SET_MAXSEGSZ_HINT) 

setmax Pointer to a boolean value that indicates that maximum segment selection is 

enabled (e.g. 0 => no max segment, ~0 => max segments) 

Return Values 

Upon successful completion, a value of zero (0) is returned. Non-zero values are described in the Error 
Conditions. 

Error Conditions 

The ioctl(HPSSFS_SET_MAXSEGSZ_HINT) routine is unsuccessful if any of the following are true: 

ENOTTY File descriptor is not associated with an HPSS file 

EFAULT Pointer value is invalid 

EBADF File descriptor was not obtained in write mode 

EPERM Data length for the file is not zero 

See Also 

HPSSFS_SET_COS_HINT and HPSSFS_SET_FSIZE_HINT 

Clients 

HPSS File System clients 

Notes 

The file descriptor must be opened in write mode (i.e. O WRONLY or O RDWR). 

Example Usage 

Create the HPSS file, with the open(2) or create(2) system call. 

Issue the HPSS_SET_MAXSEGSZ_HINT ioctl(2) system call. 

Write data to the file. 

6.1.5. HPSSFS_PURGE_CACHE 

Purpose 

Purge cached data for the file 
Synopsis 

#include <linux/hpssfs.h> 

int 
ioctl( 

int fd, /* IN 

int cmd, /* IN 

off_t *purge); /* IN 


- Open file descriptor */ 

- Command (HPSSFS_PURGE_CACHE) */ 

- Purge flag */ 
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Description 

This function is used to purge all data from the page cache for the open file, specified by the file descriptor, 
fd. Subsequent file access will require the data the be read from HPSS disks. 

Parameters 

fd Open file descriptor 

cmd Command to execute (i.e. HPSSFSPURGECACHE) 

purge Pointer to a boolean value that indicates that the cache is to be purged (e.g. 0 => 

no purge of cache, ~0 => purge cache) 

Return Values 

Upon successful completion, a value of zero (0) is returned. Non-zero values are described in the Error 
Conditions. 

Error Conditions 

The ioctl(HPSSFS_PURGE_CACHE) routine is unsuccessful if any of the following are true: 

ENOTTY File descriptor is not associated with an HPSS file 

EFAULT Pointer value is invalid 

See Also 

None. 

Clients 

HPSS File System clients 

Notes 

None. 

Example Usage 

Open the HPSS file, with the open(2) system call. 

Issue the the HPSSPURGEDATA ioctl(2) system call. 
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Chapter 7. Configuration Parser Functions 

This chapter specifies the HPSS configuration parser interface. The configuration parser is used to parse the contents 
of the HPSS.conf file, and the user should refer to the HPSS.conf man pages for the syntax and terminology. 
Specifically, the following information is provided here: 

• Application Programming Interfaces (APIs) 

• Data Definitions 

Configuration Parser Interfaces 

This section describes all configuration parser interfaces which are provided for use by another HPSS subsystem or 
by a client external to HPSS. The configuration parser interface specification includes the following information: 

• Name 

• Purpose 

• Synopsis 

• Description 

• Parameters 

• Return Values 

• Error Conditions 

• See Also 

• Notes 

The Configuration Parser has been rewritten for HPSS 6.2. 

7.1.1. hpsscfgx_ConfGetClientlnterfaces 

Purpose 

Lookup client interfaces by host 

Synopsis 

int 

hpsscfgx_ConfGetClientInterfaces( 
char *hostName, 

char *serverName, 

int *nwlfCount, 

struct in_addr **nwIfList, 
char *nwIfNames) ; 


/* IN */ 
/* IN */ 
/* OUT */ 
/* OUT */ 
/* OUT */ 


Description 

This function looks up a list of client interfaces that match the supplied hostname (if non-NULL) 

Parameters 

hostName Client Hostname to use for the search (Null is local host) 

serverName Remote host to use for the search 


HPSS Programmer's Reference 
Release 6.2 (Revision 2.0) 


July 2008 


303 





nwlfCount The number of Interfaces found 

nwIfList A malloced list of the found client Network Addresses (132.111.13.1) 

nwIfNames A malloced list of the found client Interface Names (ethO) 

Return Values 

Success (0) or error code. 

Error Conditions 

ermo System error code. 

HPSS ENOENT No entries found 

See Also 

None. 


Notes 


7.1.2. hpss_CfgParse 

Purpose 

Build the internal configuration table. 

Synopsis 

int 

hpss_CfgParse( 

char *cfgPath, /* IN */ 

hpss_cfg_stanza_t **Head, /* OUT */ 

int *parseErr, /* OUT */ 

int *errLine) ; /* OUT */ 


Description 

This function is called to parse a configuration file containing stanzas of the form defined for the 
HPSS.conf fde. See the comments in hpss_config_api.h for details of the file structure. 

If the file is parsed successfully, then the head of the linked list of stanzas is returned to the caller in Head. 
On success, the number of lines in the configuration file is returned in errLine; if a fatal parse error occurs, 
errLine is set to the line number (starting at 1) on which the error was detected. parseErr contains the 
specific error code. 

Parameters 

cfgPath Pathname to the Configuration file name 

Head Pointer to the head of the parsed entries. 

ParseErr Pointer to the parse error code 

errLine Pointer to the line number containing the error. 

Return Values 
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0 or -1 

Error Conditions 

parseErr Points to internal parsing error values 

errLine Points to the number of lines in the file or the line in the file where the error was 

observed. See hpss_config_api.h for definitions. 

HPSSEINVAL More than one configuration table open at one time. 

See Also 

None. 

Notes 

The caller is responsible for calling :!ksh to free up memory for the list when it is no longer needed. 

7.1.3. hpss_CfgFindToken 

Purpose 

Find a token within a key. 

Synopsis 

hpss_cfg_stanza_t * 
hpss_CfgFindToken( 

char *searchToken 

hpss_cfg_stanza_t *cfgStart) , 
int keyOrValue, 

int subLevels); 

Description 

This function is called to search for a white-space separated token within a key for a particular level. 
Parameters 

searchToken 
cfgStart 
keyOrValue 
subLevels 
Return Values 

NULL Token NOT found 

Non-NULL Pointer to the entry. 

Error Conditions 

None 

See Also 


Token for which to search. 

Pointer to starting Location. 

Search Criteria (Key or Value) 

Search this level ONLY or recursively. 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
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None 


Notes 

None 


7.1.4. hpss_CfgFindKey 

Purpose 

Search for a Specific Key 

Synopsis 

hpss_cfg_stanz a_t 
hpss_CfgFindKey( 

char *searchStr, 

hpss_cfg_stanza_t *cfgStart), 
int caseFlag); 


/* IN */ 
/* IN */ 
/* IN */ 


Description 

This function is called to search for a Key value for a particular level. If caseFlag is 0, then the search is 
case-sensitive, otherwise, the search is case-insensitive. 

Parameters 


Token for which to search. 

Pointer to starting Location. 

Search Criteria (Sensitive / Non-Sensitive) 

Key NOT found 
Pointer to the entry. 

None 

See Also 

None 

Notes 

None 


searchStr 

cfgStart 

caseFlag 

Return Values 
NULL 
Non-NULL 
Error Conditions 


7.1.5. hpssFree 

Purpose 

Find the specified hostname. 

Synopsis 

void 
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*Head) ; 


/* IN */ 


hpss_CfgFree( 

hpss_cfg_stanza_t 


Description 

Recursively free all the linked lists startint Head 

Parameters 

Head Pointer to the start of the list. 

Return Values 

None 

Error Conditions 

None 

See Also 

None 

Notes 


7.1.6. hpsscfgx_LookupHostName 

Purpose 

Find the specified hostname. 

Synopsis 

hpss_cfg_stanza_t * 
hpsscfgx_LookupHostName( 
hpss_cfg_stanza_t 
char 
int 


*hostStanzaList, /* IN */ 

*hostName, /* IN */ 

ignoreDomain); /* IN */ 


Description 

This function attempts to find a substanza for the hostname contained in the hostName parameter in the 
linked list of hostnames whose head is pointed to by the hostStanzaList parameter. 

The name is searched for literally, i.e., if it contains a domain name, then the client host entry must also 
contain a domain name or a wildcard pattern in order to match, except that if the ignoreDomain flag is 
TRUE, then any domain name is first stripped from the passed-in hostname. 

The client host list contains one or space-separated names for the KeyString member of the 

hpss cfg stanza t structure. Each of these is treated as a pattern, which can contain zero or more wildcard 

characters. For example, the entry: 

mda-? mda-?.sdsc.edu = { 

} 

would match any of the following hostnames: 
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mda-1 mda-7 mda-3.sdsc.edu 

If the ignoreDomain parameter is TRUE, then the domain name part of hostName (if included as part of 
the name) is ignored. 

Parameters 

hostStanzaList 
hostName 
ignoreDomain 

Return Values 
NULL 
Non-NULI 
Error Conditions 

None 

See Also 

None 

Notes 

None 

7.1.7. hpsscfgx_ConfParse 

Purpose 

Parse a configuration file 

Synopsis 

hpss_cfg_stanza_t * 
hpsscfgx_ConfParse(void); 

Description 

This function is called to parse a configuration file, if it can be found, creating an internal 
"hpssCfgEntries" table. The configuration file is looked for in a number of places, in the following order: 

1. The Configuration file directory specified in the HPSS CFG FILE PATH environment variable. 

2. If hpsscfgx_ConfSetPathDirs was called prior to this call, the paths to the configuration file to be 
parsed is contained in the <hpssConfPathDir> global variable. 

3. In /usr/local/etc 

4. In /var/hpss/etc 

For cases 2-4, the name of the Configuration File will be HPSS.conf file unless the 
hpss_ConfSetFileName() routine has been called prior to calling this routine. 

If the hpss CfgEntries table has already been built, then this call does nothing. It is necessary to free and 
NULL hpss CfgEntries to perform this routine more than one time. 


Entry not found. 
Pointer to entry 


Pointer to the start of the list. 

Host name for which to search. 

Flag specifying whether or not the Domain Name should be ignored. 
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Parameters 

None. 

Return Values 

NULL Configuration file not found. 

Non-NULL Pointer to the parsed table. 

Error Conditions 

None 

See Also 

None 

Notes 

None 

7.1.8. hpsscfgx_ConfSetPathDirs 

Purpose 

Set search path(s) for the configuration files. 

Synopsis 

int 

hpsscfgx_ConfSetPathDirs( 

char *thePathString) /* IN */ 

Description 

This function provides an API to allow the application to supply the path(s) to be searched for the 
configuration file. These paths will be checked first when the file is parsed (in function 
hpsscfgx_ConfParse) unless the HPSS CFG FILE PATH environment variable is set. 

Parameters 

thePathString The path(s) to be searched. Multiple paths may be specified separated by a colon 

(:), e.g. /usr/local/etc:/var/hpss/etc 


Return Values 

0 

Error Conditions 

HPSSEFAULT 

HPSSENOMEM 

See Also 

None 


Success. 

Null pathname passed in. 
Memory allocation error. 
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Notes 

1. If multiple calls are made, the last one overrides. 

2. The colon character cannot be part of the path. 

7.1.9. hpsscfgx_ConfSetFileName 

Purpose 

Set the name of the configuration file. 

Synopsis 

int 

hpsscfgx_ConfSetFileName( 

char *theFileName) /* IN */ 

Description 

This function provides an API to allow the application to supply an alternate configuration filename to be 
used. The default will be HPSS.conf. 

Parameters 

theFileName The name of the configuration file. 

Return Values 

0 Success. 

Error Conditions 

HPSSEFAULT Null pathname passed in. 

HPSSENOMEM Memory allocation error. 

See Also 

None 

Notes 

1. If multiple calls are made, the last one overrides. 

7.1.10. hpsscfgx_ConfSetDirPaths 

Purpose 

Set the name of the configuration file. 

Synopsis 

int 

hpsscfgx_ConfSetDirPaths( 

char *theDirName) /* IN */ 

Description 

This function provides an API to allow the application to supply an alternate directory path to be used. The 
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default is specified by the value of the HPSS CFG FILE PATH environment variable, /usr/local/etc, or 
/var/hpss/etc inthat order. 


theDirName The name of the path to the configuration file. 

Return Values 


0 Success. 

Error Conditions 

HPSS EFAULT Null pathname passed in. 

HPSS ENOMEM Memory allocation error. 

See Also 

None 


Notes 


None 

7.1.11. hpsscfgx_NetoptFindEntry 

Purpose 

Searches through the network option table, if present, to find network options configured for the specified 
address. 

Synopsis 

int 

hpsscfgx_NetoptFindEntry( 

caddr_t *NetAddr, /* IN */ 

netopt_entry_t **RetEntryPtr) /* OUT */ 


Description 

Rumbles through the network option table, attempting to initialize the table if not already done, to find an 
entry that matches the specified address - returning a pointer to the table entry. 

If a Default host entry was defined in the Network Options section of the HPSS.conf file, then it will always 
be returned if no other matching entry is found. If multiple Default entries were mistakenly configured, the 
first such entry will be used. 

Parameters 

NetAddr Address to be searched for. 

RetEntryPtr Pointer to table entry. 

IgnoreDomain Flag specifying whether or not the Domain Name should be ignored. 

Return Values 
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Error Conditions 


Success. 

No Entry Found 


None 


See Also 


None 


Notes 


None 

7.1.12. hpsscfgx_NetoptSetSock 

Purpose 

Using either a network address passed as the second parameter or an address determined from the file 
descriptor first parameter, set the socket options for the file descriptor and set the global NetOpt variables. 

Synopsis 

int 

hpsscfgx_NetoptSetSock( 

int *Fd, /* IN */ 

struct sockaddr *NetAddress ); /* IN */ 


Description 

First determine the remote network address from first NetAddress or second from the connected socket. 
Lookup up the network options. Use setsockopt to set the network options. 

Parameters 

Fd File descriptor. 

NetAddress Network address. 

Return Values 

0 Success. 

-1 No Entry Found 

Error Conditions 

None 

See Also 

None 

Notes 

None 


HPSS Programmer's Reference 
Release 6.2 (Revision 2.0) 


July 2008 


312 



7.1.13. hpsscfgx_NetoptGetWriteSize 


Purpose 

Return the network (TCP/IP) write size to be used for the specified connection. 

Synopsis 

int 

hpsscfgx_NetoptGetWriteSize( 

int SocketDescriptor, /* IN */ 

long IpAddr); /* IN */ 


Description 

Attempts to find a network option entry for the specified connection (based on the local address) - if found 
and the entry contains a non-zero value for the network write size, that value is returned. Otherwise, the 
default value (based on the presence of the "HPSS TCP WRITESIZE" environment variable) is returned. 
If the IpAddr is 0 on entry, then it is determined by getting the peer address for the socket. 

Parameters 

SocketDescriptor Connection file descriptor. 

IpAddr IP address of the connection 

Return Values 

Size Size to be used. 

Error Conditions 

None 


See Also 


None 


Notes 


None 

7.1.14. hpsscfgx_PatternMatch 

Purpose 

Pattern match function. 

Synopsis 


/* IN */ 
/* IN */ 
/* OUT */ 


hpsscfgx_PatternMatch( 

char *theString, 

char *thePattern, 

int *patternError ); 


Description 
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This function implements CSH-style pattern matching for a candidate string (theString) and a pattern 
(thePattem). See the prologue to "matchPattem" for a description of the pattern matching. If an error is 
encountered on the pattern string, then *pattemError is set non-zero. 

Parameters 

theString 
thePattern 
pattemError 

Return Values 

TRUE Match found. 

FALSE No match found. 

Error Conditions 

None 

See Also 

None 


String to test for a pattern match. 
Pattern to compare against. 

Set non-zero on exit if pattern error. 


Notes 


7.1.15. hpsscfgx_GetRestrictedPorts 

Purpose 

Read and set the restricted ports 

Synopsis 

void 

hpsscfgx_GetRestrictedPorts( 

static int minPort, /* OUT */ 

static int maxPort) /* OUT */ 


Description 

This function is called to get the range of restricted ports that are allowed, based upon the environment 
variables: 

RPCRESTRICTEDPORTS Set to restrict which ports are used for communication. 

HPSS PFTPC PORT RANGE When RPC RESTRICTED PORTS is not used, use this environment 
variable to restrict the ports used for communication. This is for 
compatibility with PFTP. 

RPC RESTRICTED PORTS takes precedence, if both are specified. 

If no ports are restricted, the function returns: 
minPort = 0 
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maxPort = 65535 

Parameters 

minPort The minimum port range value. 

maxPort The maximum port range value. 

Return Values 

None 

Error Conditions 

None 

See Also 

None 

Notes 

None 

Architecture Independent (ai) thread, mutex, condition routines - require platform specifications in 

aithreaddefs.h 

7.1.16. ai_thread_abort 

Purpose 

Abort or cancel a thread. 

Synopsis 

int 

ai_thread_abort( 

ai_thread_t theThread ); /* IN */ 

Description 

This function initiates the abort or cancel of a thread. 

Parameters 

theThread Thread to be terminated. 

Return Values 

Success (0) or error code. 

Error Conditions 

ermo System error code. 

See Also 

None. 

Notes 
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None 


7.1.17. ai_thread_detach 

Purpose 

Detach a thread. 

Synopsis 

int 

ai_thread_detach( 

ai_thread_t theThread) ; /* IN */ 

Description 

This function is called to indicate that ai threadjoin will never be called on the given thread. 

Parameters 

theThread Thread ID to be detached. 

Return Values 

Success (0) or error code. 

Error Conditions 

ermo System error code. 

See Also 

None. 

Notes 

None. 

7.1.18. ai_thread_exit 

Purpose 

Exit a thread 

Synopsis 

void 

ai_thread_exit( 

void *Status ); /* OUT */ 

Description 

This function terminates the calling thread. The result is passed to the thread that joins the caller, or is 
discarded if the caller is detached. 

An implicit ai thread exit occurs when the top-level (thread start) function returns [PTHREADS, 
POSIXPTHREADS] 

Parameters 
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Status 


Exit status. 


Return Values 

Success (0) or error code. 

Error Conditions 

ermo System error code. 

See Also 

None. 

Notes 

None. 


7.1.19. ai_thread_create 

Purpose 

Create a new thread 

Synopsis 

*theThread, 
threadAttr, 

* (*_Start_routine) (void *) , 
*Arg) ; 


int 

ai_thread_exit( 

ai_thread_t 

ai_thread_attr_t 

void 

void 


Description 

This function is used to start up a new thread. The attributes structure for the new thread may be passed in 
the threadAttr variable, or the constant value ai thread attr default may be used to specify default settings. 

Parameters 

theThread 
threadAttr 

*(*_Start routine) (void *) 

Arg 

Return Values 

Success (0) or error code. 

Error Conditions 

ermo System error code. 

See Also 

None. 


Thread to be started. 
Thread attributes. 

Pointer to the thread. 
Arguments for the thread. 
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Notes 


None. 

7.1.20. ai_thread_equal 

Purpose 

Check if two threads have the same thread identified (They are the same thread). 

Synopsis 

int 

ai_thread_equal( 

ai_thread_t *theFirstThread, 

ai_thread_t *theSecondThread); 

Description 

This function compares one thread identifier to another thread identifier 

Parameters 

theFirstThread First thread identifier 

theSecondThread Second thread identifier. 

Return Values 

TRUE (1) if the two threads have the same identifier. 

FALSE (0) if the two threads do not have the same identifier. 

Error Conditions 

None. 

See Also 

None. 

Notes 

Does not check whether the corresponding objects currently exist. 

7.1.21. ai_threadJoin 

Purpose 

Wait for the specified thread to terminate. 

Synopsis 

int 

ai_thread_j oin( 

ai_thread_t theThread, /* IN */ 

void **Status); /* OUT */ 

Description 
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The function causes the calling thread to wait for the termination of a specified thread. A call to this 
function returns after the specified thread has terminated, either via explicit ai_thread_exit(), or via implicit 
call by returning from the top level (startup) function. 

Parameters 

theThread Thread to terminate. 

Status Thread exit status. 

Return Values 

The thread's exit status or -1, ermo is set if a -1 is returned. 

Error Conditions 

None. 

See Also 

None. 

Notes 

None. 

7.1.22. ai_thread_self 

Purpose 

Return calling thread's thread handle. 

Synopsis 

ai_thread_t 
ai_thread_self(void); 

Description 

Get the handle for the current thread. 

Parameters 
None 
Return Values 

The handle to the callers thread structure. 

Error Conditions 

None. 

See Also 

None. 

Notes 

None. 
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7.1.23. ai_thread_sleep 

Purpose 

Put a thread to sleep for a specified time. 

Synopsis 

/* IN */ 
/* IN */ 


void 

ai_thread_sleep( 

int Seconds, 

int Microseconds ); 


Description 

This routine causes a thread to delay execution for a specific period of time. This period ends at the current 
time plus the specified interval. The routine will not return before the end of the period is reached, but may 
return an arbitrary amount of time after the period has gone by. This is due to system load, thread priorities, 
and system timer granularity. Specifying an interval of 0 seconds and 0 nanoseconds is allowed and can be 
used to force the thread to give up the processor or to deliver a pending cancel. 

Parameters 

Seconds Sleep time in seconds. 

MicroSeconds Sleep time in microseconds. 

Return Values 

None. 

Error Conditions 

None. 


See Also 


None. 


Notes 


None. 

7.1.24. ai_thread_yield 

Purpose 

Yield the processor to another thread. 
Synopsis 

void 

ai_thread_yield( 
void); 


Description 

Notifies the scheduler that the current thread is willing to release its processor to other threads of the same 
or higher priority. Note that there is no implementation-independent way defined to sleep(), and it's not 


HPSS Programmer's Reference 
Release 6.2 (Revision 2.0) 


July 2008 


320 



guaranteed that the processor will not be immediately given back to this thread. 

Parameters 
None 
Return Values 

None. 

Error Conditions 

None. 

See Also 

None. 

Notes 

None. 

7.1.25. ai_mutex_destroy 

Purpose 

Destroy a mutex created by ai mutex init. 

Synopsis 

int 

ai_mutex_destroy( 

ai_mutex_t theMutex); /* IN */ 

Description 

This function deletes a mutex object that will no longer be referenced. The effect of calling this routine is to 
reclaim storage allocated when the object was initialized by a previous call to 

aimutexalloc/aimutexinit. The results of this function are unpredictable if the the mutex object pointed 
to by theMutex does not exist (i.e., is not currently initialized). 

Parameters 

theMutex The mutex to be destroyed. 

Return Values 

None. 

Error Conditions 

None. 

See Also 

None. 

Notes 

None. 
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7.1.26. ai_mutex_init 

Purpose 

Initialize a mutex. 

Synopsis 

/* OUT */ 
/* IN */ 


int 

ai_mutex_init( 

ai_mutex_t theMutex, 
ai_mutexattr_t mutexAttr); 


Description 

This function creates a mutex and initializes it to the unlocked state. Note that this function and 
aimutexalloc do similar things, except that aimutexalloc actually mallocs memory for the mutex 
variable; this function is called to initialize a structure that already exists for example, a structure of type 
aimutext that was compiled into the program. 

Parameters 

theMutex The mutex to be initialized. 

mutexAttr Mutex attributes. 

Return Values 

Initialized mutex structure. 

Error Conditions 

None. 

See Also 

None. 

Notes 

None. 

7.1.27. ai_mutex_lock 

Purpose 

Lock a Mutex. 

Synopsis 

int 

ai_mutex_lock( 

ai_mutex_t theMutex) ; /* IN */ 


Description 

This function locks a mutex. If the mutex is locked when this call is made, the thread blocks waiting for the 
mutex to become available. The thread that has locked a mutex becomes its current owner and remains the 
owner until the same thread unlocks it. This routine returns with the mutex in the locked state, and the 
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current thread as the mutex's owner. 


Parameters 

theMutex The mutex to be locked. 

Return Values 

0 on success, -1 on error 

Error Conditions 

ermo 

See Also 

None. 

Notes 


None. 

7.1.28. ai_mutex_try_lock 

Purpose 

Non-blocking call to lock a mutex. 

Synopsis 

int 

ai_mutex_try_lock( 

ai_mutex_t theMutex ); /* IN */ 

Description 

This function locks a mutex. If the mutex is locked when this call is made, the calling thread does not wait 
for the mutex to become available. The thread that has locked a mutex becomes its current owner and 
remains the owner until the same thread unlocks it. When a thread calls this routine, an attempt is made to 
immediately lock the mutex. If the mutex is successfully locked, 1 (TRUE) is returned, and the current 
thread is then the current owner of the mutex. If the mutex is locked by another thread when this function 
is called, (FALSE) is returned, and the thread does not wait to acquire the lock. 

Parameters 

theMutex The mutex to be locked. 

Return Values 

0 on success, -1 on error 

Error Conditions 

ermo 


See Also 


None. 
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Notes 


None. 

7.1.29. ai_mutex_unlock 

Purpose 

Unlock a mutex. 

Synopsis 

int 

ai_mutex_unlock( 

ai_mutex_t theMutex ); /* IN */ 


Description 

This function unlocks a mutex, giving other threads a chance to lock it. If no threads are waiting for the 
mutex, the mutex unlocks with no current owner. If one or more threads are waiting to lock the specified 
mutex, this function causes one thread to return from its call to ai_mutex_lock(). 

Parameters 

theMutex The mutex to be unlocked. 

Return Values 

0 on success, -1 on error 

Error Conditions 

ermo 

See Also 

None. 


Notes 


The results of calling this routine are unpredictable if: 

- the specified mutex is actually unlocked at the time of the call 

- the specified mutex is currently owned by a thread other than the calling thread 

7.1.30. ai_ condition_broadcast 

Purpose 

Awaken a thread waiting on a condition variable. 

Synopsis 

int 

ai_condition_broadcast( 

ai_condition_t theCondition ); /* IN */ 


Description 

This function wakes all threads waiting for a condition variable. Calling this routine implies that data 
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guarded by the associated mutex has changed. This allows one or more waiting threads to proceed. 

Parameters 

theCondition Pointer to the condition variable. 

Return Values 

0 on success, -1 on error 

Error Conditions 

ermo 

See Also 

None. 

Notes 

None. 

7.1.31. ai_ condition_destroy 

Purpose 

Remove a condition variable. 

Synopsis 

int 

ai_condition_destroy( 

ai_condition_t theCondition ); /* IN */ 

Description 

This function deletes a condition object that will no longer be referenced. The effect of calling this routine 
is to reclaim storage allocated when the object was initialized by a previous call to ai condition init. The 
results of this function are unpredictable if the condition object pointed to by theCondition does not exist 
(i.e, was not created and initialized via call to ai condition alloc). 

Parameters 

theCondition Pointer to the condition variable. 

Return Values 

0 on success, -1 on error 

Error Conditions 

ermo 

See Also 

None. 

Notes 

None. 
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7.1.32. ai_ conditionJnit 

Purpose 

Initialize a condition variable. 

Synopsis 

int 

ai_condition_init( 

ai_condition_t theCondition, /* IN */ 

ai_condattr_t conditionAttr); /* IN */ 


Description 

This function initializes a pre-existing condition variable. Note that this function and aiconditionalloc do 
similar things, except that ai condition alloc actually mallocs memory for the variable; this function is 
called to initialize a structure that already exists, for example, a structure of type ai condition t that was 
compiled into the program or which is contained within another structure. 

Parameters 

theCondition Pointer to the condition variable. 

conditionAttr Condition attributes. 

Return Values 

0 on success, -1 on error 

Error Conditions 

ermo 


See Also 


None. 


Notes 


None. 

7.1.33. ai_ condition_signal 

Purpose 

Awaken a single thread waiting on a condition variable. 

Synopsis 

int 

ai_condition_signal( 

ai_condition_t theCondition ); /* IN */ 


Description 

This function wakes one thread waiting for a condition variable. Calling this routine implies that data 
guarded by the associated mutex has changed, so that it is possible for a single waiting thread to proceed. 
This function should be called when any thread waiting for the specified condition might find its predicate 
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true, but only if one thread needs to proceed. Use aiconditionbroadcast to wake up all threads that might 
be waiting on the condition. 

Parameters 

theCondition Pointer to the condition variable. 

Return Values 

0 on success, -1 on error 

Error Conditions 

ermo 

See Also 

None. 

Notes 


None. 

7.1.34. ai_ condition_wait 

Purpose 

Wait on a condition. 

Synopsis 

int 

ai_condition_wait( 

ai_condition_t theCondition, /* IN */ 

ai_mutex_t theMutex); /* IN */ 

Description 

This function unlocks theMutex, and suspends the calling thread until the specified condition is likely to be 
true because some other thread has called aiconditionsignal or ai condition broadcast. It then locks the 
mutex again, then resumes the thread. There's no guarantee that the condition will be true when when the 
thread is resumed, so it's up to the caller to loop calling ai condition signal until the condition it's checking 
is set to the desired state. 

Parameters 

theCondition Pointer to the condition variable. 

theMutex Pointer to the mutex. 

Return Values 

0 on success, -1 on error 

Error Conditions 

ermo 


See Also 


HPSS Programmer's Reference 
Release 6.2 (Revision 2.0) 


July 2008 


327 



Notes 


aiconditionsignal, aiconditionbroadcast 


7.1.35. ai_ condition_timedwait 

Purpose 

Wait on a condition using a timeout 

Synopsis 

int 

ai_condition_wait( 

ai_condition_t theCondition, 

ai_mutex_t theMutex, 

const struct timespec abstime); 


/* IN */ 
/* IN */ 
/* IN */ 


Description 

This function unlocks theMutex, and suspends the calling thread until the specified condition is likely to be 
true because some other thread has called ai condition signal or ai condition broadcase or the system time 
reaches the time specified in <abstime>. 

It then locks the mutex again, then resumes the thread. 

There's no guarantee that the condition will be true when when the thread is resumed, so it's up to the caller 
to loop calling ai condition wait or aiconditiontimedwait until the condition it's checking is set to the 
desired state. 

Parameters 

theCondition Pointer to the condition variable. 

theMutex Pointer to the mutex. 

abstime The time to wait 

Return Values 

0 Success. Returns initialized condition structure 

EINVAL, ETIMEOUT 

Error Conditions 

EINVAL The value specified by cond, mutex or abstime is invalid 

ETIMEOUT The system time has reached or exceeded the time specified in abstime 

See Also 

None 

Notes 

None. 
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7.2. Data Definitions 

This section describes key internal data definitions and all externally used data definitions for the configuration 
parser. The information provided is: 

• Name 

• Description 

• Format 


7.2.1. Defines 


#defme HPSS_CFG_MAX_LEVEL 

#defme HPSS_CFG_MAX_CHARS_PER_LINE 

#defme HPSS_CFGOPT_PFTPC 

#defme HPSS_CFGOPT_PFTPCIF 

#defme HPSS_CFGOPT MULTINODE 

#defme HPSS_CFGOPT_NWOPTIONS 

#defme HPSS_CFGOPT_PIPEFILE 

#defme HPSS_CFGOPT_LOCALFILE 

#defme HPSS_CFGOPT_COSSELECT 

#define HPSS_CFGOPT_PFTPD 

#defme HPSS_CFGOPT_PSI 

#defme HPSS_CFGOPT_HSI 

#defme HPSS_CFGOPT_HTAR 

#define HPSS_CFGOPT_TA 

#defme HPSSDEFAULTSTANZA 


10 

512 

"PFTP Client" 

"PFTP Client Interfaces" 
"Multinode Table" 
"Network Options" 

"Pipe File" 

"Local File Path" 

"Select COS" 

"PFTP Daemon" 

"PSi" 

"HSI" 

"HTAR" 

"Transfer Agent" 
"Default" 


/* 

* Error values returned from API functions 

*/ 

#define HPSSCFGFILEOPENERROR 
#define FfPSS_CFG_FTT. E _FMT_F.RROR 
#define HPSSCFGFTT . F. MEMER R OR 
#define HPSSCFGFTT. E PARSEERROI 
#define HPSS_CFG_FILE_PARSE_ERR02 
#define HPSSCFGFTT. E PARSEERROI 
#defme HPSS_CFG_FILE_PARSE_ERR04 


-7000 /* unable to open specified file */ 

-7001 /* file does not appear to be a config file */ 

-7002 /* memory allocation problem */ 

-7003 /* parse error - too many levels */ 

-7004 /* syntax error:not preceded by "=" */ 

-7005 /* parse error - extraneous closing "}" */ 

7006 /* parse error - missing closing "}" */ 
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#define HPSS_CFG_FTL F. OPF.N_F.RROR 
#define HPSSCFGFTT. F NOKFY 
#define HPSSCFGFTT . F. NOV AT .1 IF. 
#defme HPSSCFGFTT . F NOTCMPD 
#define HPSSCFGFTT . F. SFCTTONFMPTY 

#defme SEARCH BYKEY 
#defme SEARCH BY VALUE 
#defme SEARCH THIS LEVEL 
#defme SEARCH SUB LEVELS 
#defme CASESENSITIVE 
#defme CASEINSENSITIVE 


-7000 /* unable to open specified file */ 

-7007 /* No Key Found */ 

-7008 /* No Value Found */ 

-7009 /* Not Compound Stanza */ 

-7010 /* Empty Compound Stanza */ 

0 

1 

0 

1 

0 


7.2.2. hpss_cfg_stanza_t 

Description 

hpss_cfg_stanza_t is a linked-list of structures used to store data extracted from a specific stanza in the 
configuration file. Refer to HPSS.conf(7) for definitions and terminology. 

Format 


hpss_cfg_stanza_t has the following format: 

typedef struct _hpss_cfg_stanza_t hpss_cfg_stanza_t; 


struct _hpss_cfg_stanza_t { 


hpss_cfg_stanza_t 

int 

int 

unsigned32 

unsigned32 

u_signed64 

char 

char 

int 

hpss_cfg_stanz a_t 


*next; 

level; 

type; 

Flags32; 

LineNum; 

Val 64; 

*KeyString; 
*KeyValue; 

substanzaCount; 

*substanzaList; 


next 

Linked list of substanzas for this level 
level 

Level of this entry. 
type 
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Enumerated type for this entry 
Flai’s32 

Application-specific flags reserved for application(s) 
LineNum 

Line number within file where stanza tarts 
Val64 

Application-specific info. Reserved for application(s) 


(malloc-ed) flag string for this entry 
Kev Value 

(malloc-ed) NULL or value string for this entry 
substanzaCount 

Number of substanzas for this entry 
substanzaList 

Head of linked list of substanzas for this entry 


addr_array_t and addr_array_p have the following format: 

typedef struct addr_array_desc { 

char IFName [20]; 

char DotAddress [16]; 

unsigned long Flags; 

} addr_array_t, *addr_array_j>; 

IFName 

The name of the interface (e.g., enO). 

DotAddress 

The dotted IP address of the interface. 

Flags 

Flags associated with the address (See ifreq.ifr_flags in net/if.h). 
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Chapter 8. Real Time Monitoring 

This chapter specifies the Real Time Monitoring library calls and the programming interface. 
Specifically, the following information is provided: 

Application Programming Interface (API) for the Real Time Monitoring Service 

• Name 

• Syntax 

• Description 

• Parameters 

• Return Values 

• Error Conditions 

• See Also 

• Clients 

• Notes 

RTM Library Routines 

• Name 

• Syntax 

• Description 

• Parameters 

• Return Values 

• Error Conditions 

• See Also 

• Clients 

• Notes 

• Data Definitions 


8.1. RTM API Interfaces 

8.1.1. rtm_GetRequestEntries 

Syntax 

[idempotent, nontransactional] 
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signed32 rtm_GetRequestEntries( 
hpss_connect_handle_t 
hpss_reqid_t 
unsigned32 
unsigned32 
hpss_reqid_t 
rtm_object_t 
rtm_req_array_t 


CnhPtr, 

Reqld, 

ListName, 

Flags, 

RReqld, 

*ObjectPtr, 

**ReqArrayPtr 


/* ;ns */ 

/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/*'# */ 
/* OUT */ 


Description 

This API is the interface for returning the internally-stored request information from an HPSS Server. 

Parameters 


CnhPtr 

Reqld 

ListName 

Flags 


RReqld 

ObjectPtr 

ReqArrayPtr 


The connection handle. 

This requests request id. 

This identifies the specific request list of interest. 

An integer that determines what information to return. Only one flag value may 
be set. 

RTMFLAGONEREQUEST =0x1; Returns info on the request id in 
RReqld. 

RTM FLAG ALL REQUESTS = 0x2; Returns info on all requests known to 
the HPSS Server. 

RTM FLAG OBJECT = 0x4; Returns info on all requests relating to ObjectPtr. 
The requested request id. 

A union of objects about which request information is to be returned. Initially 
this will only be used for the bitfile id and the pv name. 

The returned request information - a conformant array. 


Return Values 

Zero indicates success. A value less than zero indicates an error and is a code that defines the error. 

Error Conditions 


HPSSEBADCONN 

HPSSEINVAL 

HPSSEMUTEXPROBLEM 

HPSSENOERROR 

HPSSENOMEM 

HPSSENOTREADY 

HPSSEPERM 

HPSSESYSTEM 


Problem with server connection. 

Invalid argument to API. 

Mutex error in locking or unlocking the request list. 
Successful return. 

hpss RPCMalloc failed to allocate memory. 

RTM list has not been initialized for the given server. 
Unauthorized caller. 

Software error. 
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See Also 


None. 


Clients 


The RTM utility called rtmu. 

Notes 


None. 

8.2. RTM API Data Definitions 

This section describes key internal data definitions and all externally used data definitions which are provided by this 
subsystem. A data definition may be represented by constructs such as data structures and constants. For each data 
definition, a description, format (including parameter descriptions), and clients which access the data definition are 
provided. 

The information provided is: 

• Name 

• Description 

• Format 

• Clients 

8.2.1. RTM Object Type Enumeration - rtm_objectname_t 

Description 

rtm_objectname_t defines an enumerated set of object types which may appear in the rtm_object_t 
structure. 


typedef enum { 

RTM_OBJECT_INVALID=0, 
RTM_OBJECT_BFID=l, 
RTM_OBJECT_PVNAME=2 
} rtm_objectname_t; 


Clients 


The RTM utility called rtmu. 

8.2.2. RTM Object Type - rtm_object_t 

Description 

This is the definition of the union rtm_object_t that holds the particular object type about which 
information is being requested. 

Format 


typedef union switch(rtm_objectname_t ObjectName) objects_u { 
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case RTM_OBJECT_INVALID: 

unsigned32 one; 

case RTM_OBJECT_BFID: 

hpssoid_t Bfld; 

case RTM_OBJECT_PVNAME: 

char PVName [ HPS S_PV_NAME_S IZE ] ; 

} rtm_object_t; 


one 

Just to have a completely separate case for invalid. 


The bitfile id about which information is being requested. 


The Physical Volume Name about which information is being requested. 

Clients 

The RTM utility called rtmu. 

8.2.3. Request Array - rtm_req_array_t 

Description 

This is the definition of the conformant array that is returned in the RTM API. This array contains the 
server request information. 

Format 

typedef struct req_array { 
struct { 
u_int 

rtm_req_array_entry_t 
}ReqArray 

} rtm_req_array_t; 

Size 

The size of the conformant array. 

ReqArray 

The conformant array of request entry data. 

Clients 

The RTM utility called rtmu. 

8.2.4. Request Entry - rtm_req_array_entry_t 

Description 

The rtm_req_array_entry_t defines one request entry in the returned conformant array of request entries. 
There may be one or more of these entries per request from a server, depending on the number of wait states 


ReqArray_len; 
*ReqArray_val ; 
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that this request has outstanding. As an example, the core server could have eight such entries to describe 
eight waits for mounts on a write to an 8-way tape class of service. 


Format 


typedef struct reqentry { 
hps s_reqid_t 
rtm_request_code_t 
rtm_state_t 
char 
uuid_t 

times tamp_sec_t 
time s tamp_se c_t 
rtm_serverspecific_t 
unsigned32 
unsigned32 
rtm_wait_reason_t 
rtm_wait_resource_t 
} rtm_req^_array_entry_t ; 


Reqld; 

ReqCode ; 

ReqState ; 

ServerDescName [HPSS_MAX_DESC_NAME]; 
ServerId; 

StartTime ; 

Update!ime; 

ServerSpecific ; 

Threadld; 

Processld; 

WaitReason ; 

WaitResource ; 


Reqld 

Requested request id. 

ReqCode 

The server-specific request code of the returned request. See the rtmrequestcodet definition below. 
ReqState 

The state of the request in the server. See the rtm state t definition below. 

ServerDescNam e 

The descriptive name of the executing server e.g. CORE. 

Server Id 

The server id of the executing server. 

StartTime 

The time this request started in this server. 

UpdateTime 

The time this request information was last updated by this server. 

ServerSpecif ic 

A server-specific structure that has information about the request that is appropriate to that server. 
ThreadID 

The server thread id that is handling the specific request wait-state being described. 

Processld 

The server process id that is handling the specific request wait-state being described. The HPSS Mover has 
processes and not threads. 
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WaitReason 


Server-specific integer indicating reason for waiting. See the definition of rtmwaitreasont below. 
WaitResource 

This field is the resource being waited on. See the definition of rtmwaitresourcet below. 


The RTM utility called rtmu. 

8.2.5. Request Code Enumeration - rtm_request_code_t 

Description 

The rtm_request_code_t defines an enumerated set of request codes. Each server has its own set of request 
codes with its own numbering range. 

Format 


typedef enum { 

RTM_INVALID_REQ = 0, 
RTM_CORE_CREATE_REQ = 1, 
RTM_CORE_OPEN_REQ = 2, 
RTM_CORE_CLOSE_REQ = 3, 

RTM_CORE_UNLINK_REQ = 4, 
RTM_CORE_READ_REQ = 5, 

RTM_CORE_WRITE_REQ = 6, 
RTM_CORE_SET_ATTRIB_BF_REQ = 7, 
RTM_CORE_SET_ATTRIB_BF_0_REQ = 8, 
RTM_CORE_GET_ATTRIB_BF_REQ = 9, 
RTM_CORE_GET_ATTRIB_BF_0_REQ = 10, 
RTM_CORE_MIGRATE_REQ = 11, 
RTM_CORE_STAGE_REQ = 12, 
RTM_CORE_STAGE_BACKG_REQ = 13, 
RTM_CORE_CLEAR_REQ = 14, 
RTM_CORE_PURGE_REQ = 15, 
RTM_CORE_MODIFY_REQ = 16, 
RTM_CORE_COPYFILE_REQ = 17, 
RTM_CORE_TAPE_WRITE_REQ = 18, 
RTM_CORE_TAPE_READ_REQ = 19, 
RTM_CORE_TAPE_MOVE_SEG_REQ =20, 
RTM_CORE_TAPE_POSITION_REQ = 21, 
RTM_CORE_TAPE_CREATE_RSRC_REQ =22, 
RTM_CORE_TAPE_DELETE_RSRC_REQ =23, 
RTM_CORE_TAPE_WTM =24, 
RTM_CORE_TAPE_SET_ATTRS_REQ =25, 
RTM_CORE_TAPE_GET_ATTRS_REQ =26, 
RTM_CORE_TAPE_MOUNT_REQ =27, 
RTM_CORE_TAPE_DISMOUNT_REQ =28, 
RTM_CORE_TAPE_STARTMOUNT_REQ =29, 
RTM_CORE_DISK_WRITE_REQ =30, 
RTM_CORE_DISK_READ_REQ =31, 
RTM_CORE_DISK_MOVE_SEG_REQ = 32, 
RTM_CORE_DISK_CREATE_RSRC_REQ =33, 
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RTM_CORE_DISK_DISMOUNT_REQ =38, 
RTM_CORE_PVL_VERIFY_REQ =39, 
RTM_CORE_SHUTDOWN_REQ =40, 
RTM_CORE_PVL_DISMNT_HANDLER_REQ =41, 
RTM_C0RE_0PEN_CONNECTION_REQ =42, 
RTM_CORE_CLOSE_CONNECTION_REQ =43, 
RTM_CORE_BEGIN_SESSION_REQ =44, 
RTM_CORE_END_SE S SION_REQ = 45, 
RTM_CORE_SSM_CONNECT_REQ =46, 
RTM_CORE_SSM_NOTIFICATION_REQ =47, 
RTM_CORE_SIGNAL_HANDLER_REQ =48, 
RTM_CORE_SERVER_GET_ATTR_REQ =49, 
RTM_CORE_SERVER_SET_ATTR_REQ =50, 
RTM_CORE_SERVER_INIT_REQ =51, 
RTM_CORE_GE T_S C S TAT S_RE Q = 52, 
RTM_CORE_RESET_MAPS_REQ = 53, 
RTM_CORE_CACHE_FLUSH_REQ =54, 
RTM_CORE_PVL_CALLBACK_REQ =55, 
RTM_CORE_PING_SSM_REQ =56, 
RTM_CORE_GET_W_COND_REQ = 57, 
RTM_CORE_SET_W_COND_REQ = 58, 
RTM_CORE_GET_PV_SOID_REQ =59, 
RTM_CORE_RE SERVED_1 = 60, 

RTM_CORE_RE SERVED_2 = 61, 
RTM_MVR_READ_REQ = 62, 
RTM_MVR_WRITE_REQ = 63, 
RTM_MVR_DEV_GETATTR_REQ = 64, 
RTM_MVR_D EV_S E TAT TR_RE Q = 65, 
RTM_MVR_UNLOAD_REQ = 66, 
RTM_MVR_FLUSH_REQ = 67, 
RTM_MVR_WRITETM_REQ = 68, 
RTM_MVR_READLABEL_REQ = 69, 
RTM_MVR_WRITELABEL_REQ =70, 
RTM_MVR_CLEAR_REQ =71, 
RTM_MVR_LOAD_REQ = 72, 

RTM_MVR_LOADDISPLAY_REQ =73, 
RTM_GK_OPEN_REQ =74, 

RTM_GK_CLOSE_REQ =75, 
RTM_GK_CREATE_REQ =76, 
RTM_GK_CREATE_COMPLETE_REQ =77, 
RTM_GK_S TAGE_RE Q = 78, 
RTM_GK_STAGE_COMPLETE_REQ =79, 
RTM_GK_CLEAN_UP_CLIENT_REQ = 80, 
RTM_GK_MONITOR_REQ = 81, 

RTM_GK_PAS S_THRU_REQ = 82, 
RTM_GK_QUERY_REQ = 83, 

RTM_GK_READ_POLICY_REQ = 84, 
RTM_GK_CLOSE_CONNECTION_REQ = 85, 
RTM_GK_TERM_CONNECT_THREAD_REQ = 86, 
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RTM_GK_0 PEN_CONNE CTION_REQ = 87, 
RTM_GK_GET_ATTR_REQ = 88, 
RTM_GK_S E T_AT TR_RE Q = 89, 
RTM_GK_SRVR_GET_ATTR_REQ = 90, 
RTM_GK_SRVR_SET_ATTR_REQ = 91, 
RTM_GK_SSM_CONNECT_REQ = 92, 
RTM_GK_INITIALIZE_REQ = 93, 
RTM_GK_SIGNALTHREAD_REQ = 94, 
RTM_GK_SHUTDOWN_REQ = 95, 
RTM_GK_S SM_NOTIFICATION_REQ =96 
} rtm_request_code_t; 


Clients 


The RTM utility called rtmu. 

8.2.6. Request State - rtm_state_t 

Description 

The rtm_state_t defines the enumerated states that the request may be in. 

Format 


typedef enum { 

RTM_REQ_INVALID = 0, 
RTM_REQ_INITIALIZING = 1, 
RTM_REQ_QUEUED = 2, 
RTM_REQ_IN_PROGRE S S = 3, 
RTM_REQ_BLOCKED = 4, 
RTM_REQ_SUSPENDED = 5, 
RTM_REQ_ERROR_STATE = 6, 
RTM_REQ_COMPLETED = 7, 
RTM_REQ_NOT_INUSE = 8 
} rtm_state_t; 


Clients 


The RTM utility called rtmu. 

8.2.7. Server Request Information - rtm_serverspecific_t 

Description 

This union has a different request-information structure for each participating HPSS server. In this way 
each server is returning different kinds of information about a request. 


Format 


typedef union switch(rtm_server_type_t ServerType) Attribs_u 


case RTM_SERVER_INVALID: 
char 

case RTM_CORE_SERVER: 

rtm_core_req_attr_t 
case RTM_MVR_SERVER: 

rtm_mvr_req_attr_t 


RTMComment[RTM_COMMENT_LEN]; 

COREReqlnfo; 
MVRReqlnfo; 
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GKReqlnfo; 


case RTM_GK_SERVER: 

rtm_gk_req_attr_t 
} rtm_serverspecific_t; 

RTMComment 

rtmGetRequestEntries returns an error message here if an invalid server is specified as ServerType. 
COREReqlnfo 

This is the CORE-specific structure that returns request information from the Core Server. 
MVRReqlnfo 

This is the MVR-specific structure that returns request information from the Mover. 

GKReqlnfo 

This is the GK-specific structure that returns request information from the GateKeeper. 

The RTM Utility called rtmu. 


8.2.8. Wait Reason Enumeration - rtm_wait_reason_t 

Description 

rtm_wait_reason_t defines the enumerated set of server-specific wait reasons that HPSS servers have for 
waiting on a resource. 

Format 


typedef enum { 

RTM_WAIT_REASON_INVALID = 0, 
RTM_WAIT_CORE_SS_CREATE = 1, 
RTM_WAIT_CORE_SS_DELETE = 2, 
RTM_WAIT_CORE_SS_DELETELIST = 3, 
RTM_WAIT_CORE_SS_READ = 4, 

RTM_WAIT_CORE_SS_WRITE = 5, 

RTM_WAIT_CORE_SS_GETATTRS = 6, 
RTM_WAIT_CORE_SS_SETATTRS = 7, 
RTM_WAI T_CORE_S S_S CLAS S_S TAT S = 8, 
RTM_WAIT_CORE_SS_BEGINSESS = 9, 
RTM_WAIT_CORE_SS_ENDSESS =10, 
RTM_WAIT_CORE_SS_STARTMNT = 11, 
RTM_WAIT_CORE_NS_GETFSATTRS = 12, 
RTM_WAIT_CORE_NS_GE TNAME = 13, 
RTM_WAIT_CORE_NS_SETATTRS =14, 
RTM_WAIT_CORE_FOR_FILE = 15, 
RTM_WAIT_CORE_MOVER_REPLY = 16, 
RTM_WAIT_CORE_ASYNCH_SCHDL = 17, 
RTM_WAIT_CORE_PVL_MOUNT = 18, 
RTM_WAI T_CORE_PVL_RE SERVED_3 = 19, 
RTM_WAIT_CORE_PVL_GETATTRS =20, 
RTM_WAIT_CORE_PVL_ALLOCATE =21, 
RTM_WAIT_CORE_PVL_DEALLOCATE =22, 
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RTM_WAIT_CORE_PVL_CONNECT = 23, 
RTM_WAIT_CORE_PVL_CLOSE_CONNECT = 24, 
RTM_WAIT_C0RE_PVL_RESERVED_2 =25, 
RTM_WAIT_CORE_PVL_CANCEL_JOBS =26, 
RTM_WAIT_CORE_PVL_DISMOUNT =27, 
RTM_WAIT_CORE_PVL_MOUNT_NEW =28, 
RTM_WAIT_CORE_PVL_MOUNT_ADD =29, 
RTM_WAIT_CORE_PVL_MOUNT_COMMIT =30, 
RTM_WAIT_CORE_PVL_MNT_COMPLETE =31, 
RTM_WAIT_CORE_PVL_Q_GET_ATTRS = 32, 
RTM_WAIT_CORE_PVL_VOL_GET_ATTRS = 33, 
RTM_WAIT_CORE_PVL_RESERVED_1 =34, 
RTM_WAIT_CORE_MVR_READ_DATA =35, 
RTM_WAIT_CORE_MVR_WRITE_DATA =36, 
RTM_WAIT_CORE_MVR_WRITE_TM =37, 
RTM_WAIT_CORE_MVR_POSITION = 38, 
RTM_WAIT_CORE_MVR_ASSIGN_IP =39, 
RTM_WAIT_CORE_MVR_RESERVED_1 =40, 
RTM_WAIT_CORE_SESSION_RESV_l =41, 
RTM_WAIT_CORE_SESSION_BUSY = 42, 
RTM_WAI T_CORE_SE S S ION_AS SI GN_W = 43, 
RTM_WAIT_CORE_SSM_CONNECT =44, 
RTM_WAIT_CORE_SSM_NOTIFICATION =45, 
RTM_WAIT_CORE_SEG_CACHE_ENTRY =46, 
RTM_WAIT_CORE_W_CACHE_ENTRY = 47, 
RTM_WAIT_CORE_W_GETATTRS = 48, 
RTM_WAIT_CORE_PV_CACHE_ENTRY =49, 
RTM_WAIT_CORE_MAP_CACHE_ENTRY =50, 
RTM_WAIT_CORE_PV_HANDOFF =51, 

RTM_WAIT_CORE_RESERVED_5 =52, 

RTM_WAIT_CORE_UNREG_SERVICE = 53, 
RTM_WAIT_CORE_RESERVED_4 =54, 
RTM_WAIT_CORE_PV_REFERENCE = 55, 
RTM_WAIT_CORE_PV_DISMOUNT =56, 
RTM_WAIT_CORE_SEG_FREE =57, 
RTM_WAIT_CORE_RESERVED_2 =58, 

RTM_WAIT_CORE_RESERVED_3 =59, 
RTM_WAIT_MVR_DEVICE_AVAIL = 60, 
RTM_WAIT_MVR_DEVICE_OPEN = 61, 
RTM_WAIT_MVR_DEVICE_IO = 62, 
RTM_WAIT_MVR_DEVICE_POS = 63, 
RTM_WAIT_MVR_DEVICE_GET_ABSPOS = 64, 
RTM_WAIT_MVR_DEVICE_SYNC = 65, 
RTM_WAIT_MVR_DEVICE_WTM = 66, 
RTM_WAIT_MVR_DEVICE_CLOSE = 67, 
RTM_WAIT_MVR_DEVICE_REWIND = 68, 
RTM_WAIT_MVR_DEVICE_UNLOAD = 69, 
RTM_WAIT_MVR_DEVICE_DISPLAY =70, 
RTM_WAIT_MVR_CLIENT_CONN =71, 
RTM_WAIT_MVR_CLIENT_SEND = 72, 

RTM_WAIT_MVR_CLIENT_RECV = 73, 
RTM_WAIT_MVR_CLIENT_CLOSE =74, 
RTM_WAIT_MVR_PROT_RECV = 75, 
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RTM_WAIT_MVR_PROT_SEND = 76, 

RTM_WAIT_MVR_ACTIVE_INFO =77, 
RTM_WAIT_MVR_IOR_SEND =78, 

RTM_WAIT_MVR_IOD_RECV =79, 

RTM_WAIT_GK_SITE_0PEN = 80, 

RTM_WAIT_GK_SITE_0PEN_STATS = 81, 
RTM_WAIT_GK_SITE_CLOSE = 82, 
RTM_WAIT_GK_SITE_CREATE = 83, 

RTM_WAIT_GK_SITE_CREATE_STATS = 84, 
RTM_WAIT_GK_SITE_CREATE_COMPLET = 85, 
RTM_WAIT_GK_SITE_STAGE =86, 

RTM_WAIT_GK_SITE_STAGE_STATS = 87, 
RTM_WAIT_GK_SITE_STAGE_COMPLETE = 88, 
RTM_WAIT_GK_SITE_MONITOR = 89, 

RTM_WAIT_GK_SITE_PASS_THRU = 90, 
RTM_WAIT_GK_SITE_READ_POLICY = 91, 
RTM_WAIT_GK_SITE_SHUTDOWN = 92, 
RTM_WAIT_GK_RETRY = 93, 
RTM_WAIT_GK_ASYNC_QUEUE = 94, 
RTM_WAIT_GK_MO_LOCK = 95, 
RTM_WAIT_GK_SRVR_STATE_LOCK = 96, 
RTM_WAIT_GK_SSM_STATE_LOCK = 97, 
RTM_WAIT_GK_SSM_CONNECT = 98, 

RTM_WAIT_GK_SSM_NOTIFICATION = 99, 
RTM_WAIT_GK_SIGNAL = 100, 

RTM_WAIT_GK_SHUTDOWN = 101, 

RTM_WAIT_GK_SHUTDOWN_GK_IF = 102, 
RTM_WAIT_GK_SHUTDOWN_ADMIN_IF = 103, 
RTM_WAIT_GK_SHUTDOWN_AVAL_IF = 104 
} rtm_wait_reason_t; 


Clients 


The RTM Utility called rtmu. 


8.2.9. Wait Resource - rtm_wait_resource_t 

Description 

This union holds the variety of possible objects that an HPSS server might be waiting on. 


Format 


typedef union switch(rtm_wait_type_t WaitType) WaitResource_u { 
case RTM WAIT INVALID: 


char 

case RTM_WAIT_NONE: 
char 

case RTM_WAIT_COMMENT: 
char 

case RTM_WAIT_SERVER: 
uuid_t 

case RTM_WAIT_SOID: 
hpssoid_t 


RTMComment [RTM_COMMENT_LEN]; 
NOcomment [HPSS_MAX_COMMENT_LENGTH]; 
Comment [HPSS_MAX_COMMENT_LENGTH]; 
ServerId; 

Sold; 
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case RTM_WAIT_NAME: 

char Name [RTM_NAME_LEN]; 

case RTM_WAIT_JOB: 

unsigned32 PvlJob; 

case RTM_WAIT_ID: 

unsigned32 ID; 

case RTM_WAIT_ADDRESS: 

address_t Address; 

} rtm_wait_resource_t; 

RTMComment 

Comment space for rtmGetRequestEntries to leave error message. 

NOcomment 

Comment space for server storing wait state if not really 'waiting' on an event. 

Comment 

Comment space for server storing wait state when waiting on an event. 

Serverld 

This is the uuid of the HPSS server being waited-on. For example, the CORE might be waiting on the 
MVR, so the uuid of the MVR would be stored here. 

Soid 

This could be an object like a virtual volume. 

Name 

Any name, such as a physical volume name. 

PvlJob 
PVL Job Id. 

ID 

Any id, such as a volume id. 

Address 

Client device address. 


Clients 


The RTM utility called rtmu. 

8.2.10. Wait Type Enumeration - rtm_wait_type_t 

Description 

This is an enumeration of the possible objects that an HPSS server might be waiting on. 

Format 


typedef enum { 
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RTM_WAIT_INVALID = 0, 
RTM_WAIT_NONE = 1, 
RTM_WAIT_COMMENT = 2, 
RTM_WAIT_SERVER = 3, 
RTM_WAIT_SOID = 4, 
RTM_WAIT_NAME = 5, 
RTM_WAIT_JOB = 6, 
RTM_WAIT_ID = 7, 
RTM_WAIT_ADDRESS = 8, 
RTM_WAIT_MAXVALUE = 9 
} rtm_wait_type_t; 


Clients 


The RTM utility called rtmu. 

8.2.11. CORE Request - rtm_core_req_attr_t 

Description 

rtm_core_req_attr_t is the core-specific structure returned by the Core Server. 


Format 


typedef struct rtm_core_req_attr { 

unsigned32 CoreServerbitlist; 

unsigned32 Flags; 

unsigned32 Subsystemld; 

unsigned32 UserRealmld; 

u_signed64 Filesetld; 

char F/fevetVa/«e[RTMFILESETNAMELENGTH]; 

hpssoidt BfJd; 

char BfPathname \RT MB FPAT HNA M ELENGT H ]; 

unsigned32 Userid; 

unsigned32 UserGId; 

unsigned32 COSId; 

unsigned32 BFSSClassId; 

u_signed64 BFSBytesRequested; 

u_signed64 BFSBytesMoved; 

signed32 PVLJobld; 

uuidt Mvrld; 

signed32 Deviceld; 

hpssoidt Segment; 

hpssoidt W; 

char PVName [ H PSSP VN A MESIZE ]; 

relative address t CurrentRelPosition; 
absolute address t CurrentAbsPosition; 
signed32 Excess WsInUse; 

unsigned32 Familyld; 

unsigned32 SSSClassId; 

u_signed64 SSBytesRequested; 

u_signed64 SSBytesMoved; 

} rtm core req attr t; 
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CoreServer bitlist 

This is a bitlist indicating which fields within rtm_core_req_attr_t are valid. The bit position definitions are 
as follows: 

RTMCORESUBSYTEMIDBIT = 0; 

RTMCOREREALMIDBIT = 1; 

RTMCOREFILESETIDBIT = 2; 

RTMCOREFILESETNAMEBIT = 3; 

RTMCOREBFIDBIT = 4; 

RTMCOREBFPATHNAMEBIT = 5; 

RTMCOREU SERIDBIT = 6; 

RTMCOREUSERGIDBIT = 7; 

RTMCORECOSIDBIT = 8; 

RTMCOREBFSSCLASSIDBIT = 9; 

RTMCOREBFSBYTESREQUESTEDBIT = 10; 

RTMCOREBFSBYTESMOVEDBIT =11; 

RTMCOREPVLJOBIDBIT = 12; 

RTMCOREMVRIDBIT = 13; 

RTMCOREDEVICEIDBIT = 14; 

RTMCORESEGMENTBIT = 15; 

RTMCOREVVBIT = 16; 

RTMCOREPVNAMEBIT = 17; 

RTMCORECURRENTRELPOSBIT = 18; 

RTMCORECURRENTABSPOSBIT = 19; 

RTMCOREEXCESSVVSBIT = 20; 

RTMCOREFAMILYIDBIT = 21; 

RTM_CORE_SS_SCLASSID_BIT = 22; 

RTMCORESSBYTESREQUESTEDBIT = 23; 

RTM_CORE_SS_BYTESMOVED_BIT= 24; 

Flans 

For future use. 

Subsvstemld 
The Subsystem Id. 
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UserRealmid 


The realm id of the file involved in this request. 

Filesetld 

The fileset id of the file involved in this request. 

FilesetName 

The fileset pathname (if available) of the file involved in this request. 

Bad 

The Bitfile Id of the file involved in this request. 

BfPathname 

The file pathname (if available) of the file relative to the fileset. 

Userid 

The Unix userid (if available) of the user involved in this request. 

UserGid 

The Unix groupid (if available) of the user involved in this request. 

COSId 

The Class of Service of the file involved in this request. 

BFS SClassId 

The Storage Class id of the file involved in this request. 

BFS BvtesRequested 

The number of bytes requested by this request. 

BFS BvtesMoved 

The number of bytes already moved by this request. 

PVLJobld 

The PVL Job Id associated with this request. 

Mvrld 

The Mover Id associated with the Core Server wait state for this request. 
Deviceld 

The ID of the device associated with the Core Server wait state for this request. 


The Storage Segment associated with the Core Server wait state for this request. 


VV 


The Virtual Volume associated with the Core Server wait state for this request. 
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PVName 


The Physical Volume name associated with the Core Server wait state for this request. 

CurrentRelPosition 

The Current Relative Position. 

CurrentAbsPosition 

The Current Absolute Position. 

Excess Wsln Use 

This wait state occurs when the number of tape VVs in use exceeds the quota for the storage class. 
Additional requests to assign a tape W to a session block until the quota is restored. 

Familyld 

The File Family Id. 

SS SClassId 
The Storage Class Id. 

SS BvtesRequested 

The number of data bytes requested to be moved by this request. 

SS BvtesMoved 

The number of data bytes already moved by this request. 


The RTM utility called rtmu. 

8.2.12. Mover Request - rtm_mvr_req_attr_t 

Description 

This is the mover-specific structure that returns information from the Mover about this request. 


Format 


typedef struct rtm_mvr_req_attr { 
unsigned32 Mvr_bitlist; 
unsigned32 Flags; 
u_signed64 InitialTransferOffset; 
u_signed64 CurrentTransferOffset; 
long Deviceld; 

char Vol umeld [ PV_NAME_LENGTH ] ; 

u_signed64 BytesRequested; 
u_signed64 BytesMoved; 

} rtm_mvr_req_attr_t; 


Mvr bitlist 

This is a bitlist indicating which fields within rtm_mvr_req_attr_t are valid. The bit position definitions 
are as follows: 
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RTMMVRINITIALXFEROFFSETBIT = 0; 
RTMMVRCURRENTXFEROFFSETBIT = 1; 
RTMMVRDEVICEIDBIT = 2; 
RTMMVRVOLUMEIDBIT = 3; 
RTMMVRBYTESREQUESTEDBIT = 4; 
RTMMVRBYTESMOVED = 5; 

Flags 

For future use. 

Initial TransferOffset 

The initial transfer offset of the request. 

CurrentTransferOffset 

The current transfer offset of the request. 

Deviceld 

The device id of the associated device. 

Volumeld 

The volume id of the associated volume. 

BvtesRequested 

The number of bytes requested by this request. 

BvtesMoved 

The number of bytes moved thus far by this request. 

The RTM utility called rtmu. 


8.2.13. Gatekeeper Request - rtm_gk_req_attr_t 

Description 

This is the gk-specific structure that returns information from the GateKeeper about this request. 

Format 


typedef struct rtm_gk_req_attr 


unsigned32 

unsigned32 

unsigned32 

hpssoid_t 

hpss_uuid_t 

hpss_uuid_t 

hpss_uuid_t 

unsigned32 


Gk_bitlist; 

Flags; 

Author!zedCaller ; 

BitFileld; 

Connectionld; 

ClientConnectld; 

ControlNo ; 

Realmld; 
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unsigned32 
hpss_sec_sockaddr_t 
unsigned32 
unsigned32 
unsigned32 
u_signed64 
u_signed64 
unsigned32 
unsigned32 
unsigned32 
} rtm_gk_req_attr_t; 


Groupld; 

HostAddr; 

OFlag; 

RequestType ; 
StageFlags; 
StageLength; 
StageOffset; 

StagestorageLevel ; 
Userid; 

WaitTime ; 


Gk bitlist 

This is a bitlist indicating which fields within rtm_gk_req_attr_t are valid. The bit position definitions are 
as follows: 

RTMGKAUTHORIZEDCALLERBIT = 0; 

RTMGKBITFILEIDBIT = 1; 

RTMGKCLIENTCONNECTIDBIT = 2; 

RTMGKCONNECTIONIDBIT = 3; 

RTMGKCONTROLNOBIT = 4; 

RTMGKREALMIDBIT = 5; 

RTMGKGROUPIDBIT = 6; 

RTM GK HOSTADDR BIT = 7; 

RTMGKOFLAGBIT = 8; 

RTMGKREQUESTTYPEBIT = 9; 

RTM_GK_STAGEFLAGS_BIT = 10; 

RTMGKSTAGELENGTHBIT =11; 

RTMGKSTAGEOFFSETBIT = 12; 

RTMGKSTAGESTORAGELEVELBIT = 13; 

RTMGKU SERIDBIT = 14; 

RTMGKWAITTIMEBIT = 15; 


Flues 

For future use. 

AuthorizedCalter 

The authorized caller for this call. 

BitFileld 

The unique bitfile identifier associated with a file. This field is zero for file creates. 
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Connectionld 


The unique connection identifier associated with the Gatekeeper's client process (usually CORE). 
ClientConnectld 

The unique connection identifier associated with the end user client process, namely the connection Id 
between the end client and CORE. 

ControlNo 

The unique gatekeeper request identifier. Used as a unique key and for identifying a particular client 
request. 

Realmld 

The HPSS-defined integer identifier of the Realm. This should be used in conjunction with the Userid to 
uniquely identify a user. 

Groupld 

The UNIX Group Id of the user opening the file. 

HostAddr 

The address of the host that the user is on. 

Oflag 

Specifies the open file status flags (e.g. ORDONLY). 

RequestTvpe 

The type of gatekeeping request. Possible request types are: 

RTMGKCREATEREQUEST 

RTMGKOPENREQUEST 

RTMGKSTAGEREQUEST 

StageFlags 

Controls the behavior of the stage request. Valid values include: 

CORE STAGE ALL: Stage entire file. 

CORE ASYNC CALL: Return after initiating stage. 

Specifies the length of the data to be staged. 

StaseOffset 

Specifies the offset of the start of the data to be staged. 

StageStorageLevel 

Identifies the level in the storage hierarchy to which the data is to be staged. 

Userid 
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The UNIX Userid of the user that is opening the file. This should be used in conjunction with the Realmld 
to uniquely identify a user. 

WaitTime 

The number of seconds the Client API has to wait before retrying an open request that returned the status 
HPSSERETRY. 

Clients 

The RTM utility called rtmu. 

8.3. RTM Library Routines 
8.3.1. rtmjnit 

Syntax 

signed32 
rtm_Init ( 

char *ServerName, 

s e c_au th z_ve c tor_t * ServerAuthzVector) 

Description 

This routine is called once by each server to register the RTM interface using hpss_RPCRegisterService 
and to create a separate thread pool for this interface. It also initializes the RTM list mutex, copies the 
server authzvector to a known RTM global, opens the master catalog for log messages, and starts the thread 
that will delete entries from the delayed-delete lists (routine rtm delete thread - see pseudo code). 

Parameters 

ServerName The server name. 

ServerAuthzVector The Server authorization vector. 

Return Values 

Zero indicates success. A non-zero return indicates an error and is a code that defines the error. 

Error Conditions 

HPSSENOERROR Initialization OK. 

HPSS EMUTEX PROBLEM Failed to initialize a mutex. 

Errors as returned from hpss_RPCRegisterService. 

See Also 


/* IN */ 
/* IN */ 


rtmShutdown 

Clients 


Participating HPSS servers 

Notes 


None. 
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8.3.2. rtm_Shutdown 

Syntax 

signed32 
rtm_Shutdown ( 
void); 

Description 

This routine calls hpss_RPCUnregisterService for the RTM interface. 

Parameters 

none 

Return Values 

Zero indicates success. A non-zero return indicates an error and is a code that defines the error. 

Error Conditions 

Returns the error returned by hpss_RPCUnregisterService. 

See Also 

rtmlnit 

Clients 

Participating HPSS servers 

Notes 


None. 


8.3.3. rtm_ReqListlnit 

Syntax 


#include "rtm_reqlist.h" 
signed32 


rtm_ReqListInit ( 
unsigned32 
char 

unsigned32 
hpss_uuid_t 
rtm_reqlist_t 


ListName, 

* ServerDescName, 
ServerType, 
Serverld, 
**ListPtrPtr) ; 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 


Description 

This routine is an initialization routine to set up a request list. It locks the header list and initializes the 
header list itself the first time through. It mallocs space for a ReqList, and initializes the specific request 
list, including its protective mutex. It initializes the DeleteList associated with this request list. It then 
unlocks the header list. 


Parameters 
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ListName 


The request list to be initialized, e.g. 
RTMCOREDEFAULTREQLIST. 

ServerDescName The Server Descriptive Name of the requesting server, e.g.CORE. 

ServerType The Server Type of the requesting server, e.g. 

RTMCORESERVER. 

Serverld The Server Id of the requesting server. 

ListPtrPtr A pointer to the pointer to the request list that was initialized. This 

will be passed in subsequent calls to the rtm library routines. 


Return Values 

Zero indicates success. A non-zero return indicates an error and is a code that defines the error. 


Error Conditions 


HPSSENOERROR 
HPSS_ EINVAL 
HPSSEMUTEXPROBLEM 
HPSSENOMEM 


Initialization OK. 

Initialization routine was already called. 
Failed to initialize mutex, 
malloc failed. 


See Also 


rtmReqListlnsertEntry 

Clients 


Participating HPSS servers 


Notes 


8.3.4. rtm_ReqListlnsertEntry 

Syntax 

#include "rtm_reqlist.h" 
signed32 

rtm_ReqListInsertEntry ( 


rtm_reqlist_t 

*ListPtr, 

/* IN */ 

hpss_reqid_t 

Reqld, 

/* IN */ 

rtm_request_code_t 

ReqCode, 

/* IN */ 

rtm_state_t 

ReqState, 

/* IN */ 

rtm_req_entry_t 

**EntryPtr) ; 

/* OUT */ 


Description 

This routine is called by each participating HPSS server to insert a new request entry in the request list and 
return a pointer to the entry. It uses malloc() to create a new request list entry node. Multiple request 
entries per request id may be entered by a server if the request enters the server multiple times, or if the 
server wishes to separate the entries for any reason. 

Parameters 
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ListPtr 


A pointer to the request list that was returned from the rtm_ReqListInit call. 
Reqld The Request ID of the current request. 

ReqCode The server-specific request code, e.g. RTMCORECREATEREQ. 

ReqState The request state, e.g. RTM REQ IN PROGRESS. 

EntryPtr A pointer to the new request list entry pointer. 

Return Values 

Zero indicates success. A non-zero return indicates an error and is a code that defines the error. 

Error Conditions 

HPSSENOERROR Initialization OK. 

HPSS_ EINVAL Invalid ListPtr was passed in. 

HPSS EMUTEX PROBLEM Failed to lock or unlock a mutex 
HPSS ENOMEM Malloc failed. 

See Also 

rtmReqListDeleteEntry 

Clients 

Participating HPSS servers 

Notes 

None. 

8.3.5. rtm_ReqListDeleteEntry 

Syntax 

#include "rtm_reqlist.h" 
signed32 

rtm_ReqListDeleteEntry ( 
rtm_reqlist_t 
hps s_reqid_t 
rtm_req_entry_t 
unsigned32 

Description 

This routine is called by each participating HPSS server to delete a request entry from the request list. It 
scans the request list looking for this entry. If Seconds is zero, it unlinks the entry, and frees the memory 
associated with the request entry and all its waitlist entries. If Seconds is non-zero, it puts the request entry 
pointer onto the DeleteList. 

Parameters 

ListPtr A pointer to the request list that was returned from the rtm_ReqListInit call. 

Reqld The Request ID of the current request. 


*ListPtr, /* IN */ 
Reqld, /* IN */ 
* EntryPtr, /* IN */ 
Seconds) ; /* IN */ 
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EntryPtr 

Seconds 


A pointer to the entry to delete. 

The number of seconds to delay before deleting this request entry. 


Return Values 

Zero indicates success. A non-zero return indicates an error and is a code that defines the error. 

Error Conditions 

HPSS E NOERROR Initialization OK. 

HPSS_ EINVAL Invalid argument was passed in. 

HPSS EMUTEX PROBLEM Failed to lock or unlock a mutex 
HPSS ESYSTEM Software error. 


See Also 


rtmReqListlnsertEntry 

Clients 


Participating HPSS servers 

Notes 


None. 

8.3.6. rtm_ReqListUpdateEntry 

Syntax 

#include "rtm_reqlist.h" 
signed32 

/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 


rtm_KeqL.istupaateJ!;ntry ( 
rtm_reqlist_t 
hpss_reqid_t 
rtm_req_entry_t 
rtm state t 


*ListPtr, 
Reqld, 
*EntryPtr, 
ReqState) ; 


Description 

This routine is called by each participating HPSS server to update the state of an existing request entry. 

Parameters 

ListPtr A pointer to the request list that was returned from the rtm_ReqListInit call. 

Reqld The Request ID of the request entry to update. 

EntryPtr A pointer to the request entry to update. 

ReqState The new request state. 

Return Values 

Zero indicates success. A non-zero return indicates an error and is a code that defines the error. 

Error Conditions 
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HPSS_E_NOERROR Initialization OK. 

HPSS_ EINVAL EntryPtr argument is NULL. 

HPSSEMUTEXPROBLEM Failed to lock or unlock a mutex 


See Also 


rtmReqListlnsertEntry, rtm ReqListDeleteEntry 


Clients 


Participating HPSS servers 

Notes 


8.3.7. rtm_WaitListlnsertEntry 

Syntax 

#include "rtm_reqlist.h" 
signed32 

rtm_WaitListInsertEntry ( 
rtm_reqlist_t 
hpss_reqid_t 
rtm_state_t 
rtm_req_entry_t 
rtm_serverspecific_t 
rtm_wait_reason_t 
rtm_wait_resource_t 
rtm_wait_entry_t 


*ListPtr, 

Reqld, 

ReqState, 

* EntryPtr, 

*ServerSpecific, 
WaitReason, 

WaitResource, 
**WaitEntryPtr ); 


/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* IN */ 
/* OUT */ 


Description 


This routine is called by an HPSS server to insert a new waitlist entry into the request entry indicated by 
EntryPtr. It uses malloc() to create a new waitlist entry node, inserts this waitlist entry at the front of the 
request's waitlist, and returns a pointer to the waitlist entry. 


Parameters 

ListPtr 
Reqld 
ReqState 
EntryPtr 
Serverspecific 
WaitReason 
WaitResource 
WaitEntryPtr 
Return Values 


A pointer to the request list that was returned from the rtm_ReqListInit call. 
The Request ID of the request entry of interest. 

The current Request State of the request entry of interest, or zero for no change. 
A pointer to the request entry to add this waitlist entry to. 

The server-specific structure that pertains to this waitlist entry. 

An enumerated list that explains why the server is in a wait state. 

The WaitResource being waited on, e.g. a volume id. 

A pointer to the new waitlist entry pointer. 


HPSS Programmer's Reference 
Release 6.2 (Revision 2.0) 


July 2008 


357 




Zero indicates success. A non-zero return indicates an error and is a code that defines the error. 


Error Conditions 

HPSS_E_NOERROR Initialization OK. 

HPSS_EMUTEX_PROBLEM Failed to lock/unlock a mutex 
HPSS ENOMEM Malloc failed. 

HPSS EINVAL Invalid value was passed in. 

See Also 

rtmReqListlnsertEntry, rtmReqListDeleteEntry, rtmWaitListDeleteEntry 

Clients 

Participating HPSS servers 

Notes 

None. 

8.3.8. rtm_WaitListDeleteEntry 

Syntax 


#include rtm_reqlist.h 
signed32 

rtm_WaitListDeleteEntry ( 

rtm_reqlist_t *ListPtr, /* IN */ 

hps s_reqid_t Reqld, /* IN */ 

rtm_state_t ReqState, /* IN */ 

rtm_req_entry_t *EntryPtr, /* IN */ 

rtm_wait_entry_t *WaitEntryPtr ); /* IN */ 


Description 

This routine is called by an HPSS server to delete a waitlist entry from the given request entry. It locks the 
request list, scans the waitlist entries for the given request entry, and deletes the waitlist entry and frees the 
memory. 

Parameters 

ListPtr A pointer to the request list that was returned from the rtm_ReqListInit call. 

Reqld The Request ID of the current request. 

ReqState The current Request State of the request entry of interest, or zero for no change. 

EntryPtr A pointer to the request entry from which to delete this waitlist entry. 

WaitEntryPtr A pointer to the waitlist entry to delete. 

Return Values 

Zero indicates success. A non-zero return indicates an error and is a code that defines the error. 

Error Conditions 
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HPSS_ EINVAL Invalid argument was passed in. 

HPSSENOENT Waitlist entry not found. 

HPSS_E_NOERROR Initialization OK. 

HPSSEMUTEXPROBLEM Failed to lock/unlock a mutex. 


See Also 


rtmReqListlnsertEntry, rtmReqListDeleteEntry, rtmWaitListlnsertEntry 


Clients 


Participating HPSS servers 

Notes 


8.3.9. rtm_WaitListUpdateEntry 

Syntax 

#include "rtm_reqlist.h" 
signed32 

rtm_WaitListUpdateEntry ( 
rtm_reqlist_t 
hpss_reqid_t 
rtm_state_t 
rtm_req_entry_t 
rtm_wait_entry_t 
rtm_serverspecific_t 
rtm_wait_reason_t 
rtm_wait resource t 


*L±stPtr, /* IN */ 
Reqld, /* IN */ 
ReqState, /* IN */ 
*EntryPtr, /* IN */ 
*WaitEntryPtr, /* IN */ 
*ServerSpecific, /* IN */ 
WaitReason, /* IN */ 
WaitResource) ; /* IN */ 


Description 

This routine is called by an HPSS server to update the waitlist entry indicated by WaitEntryPtr, which is 
member of the waitlist in the request entry EntryPtr. 

Parameters 


ListPtr 
Reqld 
ReqState 
EntryPtr 
WaitEntryPtr 
Serverspeciflc 
WaitReason 
WaitResource 
Return Values 


A pointer to the request list that was returned from the rtm_ReqListInit call. 
The Request ID of the current request. 

The current Request State of the request entry of interest, or zero for no change. 
A pointer to the request entry containing this waitlist entry. 

A pointer to the waitlist entry to update. 

The server-specific struct that pertains to this waitlist entry. 

An enumerated integer that explains why the server is in a wait state. 

The WaitResource being waited on, e.g. a volume id. 
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Zero indicates success. A non-zero return indicates an error and is a code that defines the error. 

Error Conditions 

HPSS_E_NOERROR Initialization OK. 

HPSS EINVAL Invalid argument passed in. 

HPSS EMUTEX PROBLEM Failed to lock/unlock a mutex. 

See Also 

rtm_WaitListlnsertEntry, rtm_WaitListlnsertEntry 

Clients 

Participating HPSS servers 

Notes 

None. 
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Appendix A. Glossary of Terms and Acronyms 


ACI Automatic Media Library Client Interface 

ACL Access Control List 


ACSLS 

ADIC 

accounting 


AIX 


alarm 

AML 

AMS 

ANSI 

API 


archive 

attribute 


Automated Cartridge System Library Software (Science Technology 
Corporation) 

Advanced Digital Information Corporation 

The process of tracking system usage per user, possibly for the purposes of 
charging for that usage. Also, a log record message type used to log information 
to be used by the HPSS Accounting process. This message type is not currently 
used. 

Advanced Interactive Executive. An operating system provided on many IBM 
machines. 

A log record message type used to log high-level error conditions. 

Automated Media Library. A tape robot. 

Archive Management Unit 
American National Standards Institute 
Application Program Interface 

One or more interconnected storage systems of the same architecture. 

When referring to a managed object, an attribute is one discrete piece of 
information, or set of related information, within that object. 


attribute change 


audit (security) 


bar code 


BFS 


When referring to a managed object, an attribute change is the modification of an 
object attribute. This event may result in a notification being sent to SSM, if 
SSM is currently registered for that attribute. 

An operation that produces lists of HPSS log messages whose record type is 
SECURITY. A security audit is used to provide a trail of security-relevant 
activity in HPSS. 

An array of rectangular bars and spaces in a predetermined pattern which 
represent alphanumeric information in a machine readable format (e.g., UPC 
symbol) 

HPSS Bitfile Service. 


HPSS Programmer's Reference 
Release 6.2 (Revision 2.0) 


July 2008 


361 



bitfile 


bitfile segment 


Bitfile Service 

BMUX 

bytes between tape marks 


CAP 

cartridge 


central log 


Class of Service 


cluster 


configuration 


COS 

Core Server 


daemon 


A file stored in HPSS, represented as a logical string of bits unrestricted in size 
or internal structure. HPSS imposes a size limitation in 8-bit bytes based upon 
the maximum size in bytes that can be represented by a 64-bit unsigned integer. 

An internal metadata structure, not normally visible, used by the Core Server to 
map contiguous pieces of a bitfde to underlying storage. 

Portion of the HPSS Core Server that provides a logical abstraction of bitfiles to 
its clients. 

Block Multiplexer Channel 

The number of data bytes that are written to a tape virtual volume before a tape 
mark is required on the physical media. 

Cartridge Access Port 

A physical media container, such as a tape reel or cassette, capable of being 
mounted on and dismounted from a drive. A fixed disk is technically considered 
to be a cartridge because it meets this definition and can be logically mounted 
and dismounted. 

The main repository of logged messages from all HPSS servers enabled to send 
messages to the Log Daemon. 

A type definition in Java, ft defines a template on which objects with similar 
characteristics can be built, and includes variables and methods specific to the 
class. 

A set of storage system characteristics used to group bitfiles with similar logical 
characteristics and performance requirements together. A Class of Service is 
supported by an underlying hierarchy of storage classes. 

The unit of storage space allocation on HPSS disks. The smallest amount of 
disk space that can be allocated from a virtual volume is a cluster. The size of 
the cluster on any given disk volume is determined by the size of the smallest 
storage segment that will be allocated on the volume, and other factors. 

The process of initializing or modifying various parameters affecting the 
behavior of an HPSS server or infrastructure service. 

Class of Service 

An HPSS server which manages the namespace and storage for an HPSS system. 
The Core Server manages the Name Space in which files are defined, the 
attributes of the files, and the storage media on which the files are stored. The 
Core Server is the central server of an HPSS system. Each storage sub-system 
uses exactly one Core Server. 

A UNIX program that runs continuously in the background. 
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DB2 


debug 

DEC 

delog 

deregistration 
descriptive name 


A relational database system, a product of IBM Corporation, used by HPSS to 
store and manage HPSS system metadata. 

A log record message type used to log lower-level error conditions. 

Digital Equipment Corporation. 

The process of extraction, formatting, and outputting HPSS central log records. 
The process of disabling notification to SSM for a particular attribute change. 
A human-readable name for an HPSS server. 


device A physical piece of hardware, usually associated with a drive, that is capable of 

reading or writing data. 

directory An HPSS object that can contain files, symbolic links, hard links, and other 

directories. 


dismount 


DNS 


An operation in which a cartridge is either physically or logically removed from 
a device, rendering it unreadable and unwritable. In the case of tape cartridges, a 
dismount operation is a physical operation. In the case of a fixed disk unit, a 
dismount is a logical operation. 

Domain Name Service 


DOE Department of Energy 

drive A physical piece of hardware capable of reading and/or writing mounted 

cartridges. The terms device and drive are often used interchangeably. 

EFS External File System 

ERA Extended Registry Attribute 

ESCON Enterprise System Connection 


event A log record message type used to log informational messages (e.g., subsystem 

starting, subsystem terminating). 

A ' 

export An operation in which a cartridge and its associated storage space are removed 

from the HPSS system Physical Volume Library. It may or may not include an 
eject, which is the removal of the cartridge from its Physical Volume Repository. 

FDDI Fiber Distributed Data Interface 


file An object than can be written to, read from, or both, with attributes including 

access permissions and type, as defined by POSIX (P1003.1-1990). HPSS 
supports only regular files. 
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file family 

fileset 

fileset ID 
fileset name 
file system ID 
FTP 

Gatekeeper 

Gatekeeping Service 


Gatekeeping Site Interface 
Gatekeeping Site Policy 

GB 

GECOS 

GID 

GK 

GSS 

GUI 

HA 

HACMP 

halt 

HDM 

hierarchy 


An attribute of an HPSS file that is used to group a set of files on a common set 
of tape virtual volumes. 

A collection of related files that are organized into a single easily managed unit. 
A fileset is a disjoint directory tree that can be mounted in some other directory 
tree to make it accessible to users. 

A 64-bit number that uniquely identifies a fileset. 

A name that uniquely identifies a fileset. 

A 32-bit number that uniquely identifies an aggregate. 

File Transfer Protocol 

An HPSS server that provides two main services: the ability to schedule the use 
of HPSS resources referred to as the Gatekeeping Service, and the ability to 
validate user accounts referred to as the Account Validation Service. 

A registered interface in the Gatekeeper that provides a site the mechanism to 
create local policy on how to throttle or deny create, open and stage requests and 
which of these request types to monitor. 

The APIs of the gatekeeping site policy code. 

The gatekeeping shared library code written by the site to monitor and throttle 
create, open, and/or stage requests. 

Gigabyte (2 30 ) 

The comment field in a UNIX password entry that can contain general 
information about a user, such as office or phone number. 

Group Identifier 

Gatekeeper 

Generic Security Service 
Graphical User Interface 
High Availability 

High Availability Clustered Multi-Processing - A software package used to 
implement high availability systems. 

A forced shutdown of an HPSS server. 

Shorthand for HPSS/DMAP. 

See Storage Hierarchy. 
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HIMF 


HPSS Interim Metadata Format 


HiPPI 

HPSS 

HPSS-only fileset 

IBM 

ID 

IEC 

IEEE 

IETF 

Imex 

import 


I/O 

IOD/IOR 

IP 

IRIX 

junction 

KB 

LAN 

I.AM. 

LARC 

latency 

LCU 

LDAP 


High Performance Parallel Interface 
High Performance Storage System 

An HPSS fileset that is not linked to an external filesystem (e.g., XFS). 

International Business Machines Corporation 

Identifier 

International Electrotechnical Commission 
Institute of Electrical and Electronics Engineers 
Internet Engineering Task Force 
Import/Export 

An operation in which a cartridge and its associated storage space are made 
available to the HPSS system. An import requires that the cartridge has been 
physically introduced into a Physical Volume Repository (injected). Importing 
the cartridge makes it known to the Physical Volume Library. 

Input/Output 

Input/Output Descriptor / Input/Output Reply. Structures used to send control 
information about data movement requests in HPSS and about the success or 
failure of the requests. 

Internet Protocol 

SGI’s implementation of UNIX 

A mount point for an HPSS fileset. 

Kilobyte (210) 

Local Area Network 

Los Alamos National Laboratory 

Langley Research Center 

For tape media, the average time in seconds between the start of a read or write 
request and the time when the drive actually begins reading or writing the tape. 

Library Control Unit 

Lightweight Directory Access Protocol 
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LLNL 


LMCP 
LMU 
local log 

Location Server 

Log Client 

Log Daemon 
log record 
log record type 

logging service 

LRU 

LS 

LTO 

MAC 

managed object 


MB 

metadata 

method 

migrate 


Lawrence Livermore National Laboratory 
Library Manager Control Point 
Library Management Unit 

An optional circular log maintained by a Log Client. The central log contains 
formatted messages from all enabled HPSS servers residing on the same node as 
the Log Client. 

An HPSS server that is used to help clients locate the appropriate Core Server 
and/or other HPSS server to use for a particular request. 

An HPSS server executing on each HPSS node that is responsible for sending 
log messages to the local log, to the Log Daemon for central logging, and to 
SSM to display messages in the Alarm and Event window. 

An HPSS server responsible for writing log messages to the central log. 

A record received and maintained in a central log by the HPSS Log Daemon. 

An indicator of whether a message to be logged is an alarm, event, status, debug, 
request, security, or accounting record. 

An HPSS infrastructure service consisting of a central Log Daemon, one or more 
Log Clients, and server-specific logging policies. 

Least Recently Used 

Location Server 

Linear Tape-Open. A half-inch open tape technology developed by IBM, HP and 
Seagate. 

Mandatory Access Control 

A programming data structure that represents an HPSS system resource. The 
resource can be monitored and controlled by operations on the managed object. 
Managed objects in HPSS are used to represent servers, drives, storage media, 
jobs, and other resources. 

Megabyte (220) 

Control information about the data stored under HPSS, such as location, access 
times, permissions, and storage policies. Most HPSS metadata is stored in a 
DB2 relational database. 

A Java function or subroutine 

To copy file data from a level in the file’s hierarchy onto the next lower level in 
the hierarchy. 
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Migration/Purge Server 

MM 

mount 

mount point 
Mover 

MPS 

MRA 

MSSRM 

MVR 

NASA 

Name Service 

name space 

NERSC 

NLS 

notification 

NS 

NSL 

object 

ONC 

ORNL 

OSF 

OS/2 


An HPSS server responsible for supervising the placement of data in the storage 
hierarchies based upon site-defined migration and purge policies. 

Metadata Manager. A software library that provides a programming API to 
interface HPSS servers with the DB2 programming environment. 

An operation in which a cartridge is either physically or logically made readable 
and/or writable on a drive. In the case of tape cartridges, a mount operation is a 
physical operation. In the case of a fixed disk unit, a mount is a logical operation. 
A place where a fileset is mounted in the XFS and/or HPSS namespaces. 

An HPSS server that provides control of storage devices and data transfers 
wi th in HPSS. 

Migration/Purge Server 

Media Recovery Archive 

Mass Storage System Reference Model 

Mover 

National Aeronautics and Space Administration 

The portion of the Core Server that providesa mapping between names and 
machine oriented identifiers. In addition, the Name Service performs access 
verification and provides the Portable Operating System Interface (POSIX). 

The set of name-object pairs managed by the HPSS Core Server. 

National Energy Research Supercomputer Center 

National Language Support 

A notice from one server to another about a noteworthy occurrence. HPSS 
notifications include notices sent from other servers to SSM of changes in 
managed object attributes, changes in tape mount information, and log messages 
that are alarm, event, and status log record message types. 

HPSS Name Service 

National Storage Laboratory 

See Managed Object 

Open Network Computing 

Oak Ridge National Laboratory 

Open Software Foundation 

Operating System (multi-tasking, single user) used on the AMU controller PC 
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PB 

PFTP 

physical volume 

Physical Volume Library 
Physical Volume Repository 

PIO 

PIOFS 

POSIX 

purge 

purge lock 

PV 

PVL 

PVM 

PVR 

RAID 

RAIT 

RAM 

reclaim 

registration 

reinitialization 


Petabyte (2 50 ) 

Parallel File Transfer Protocol 

An HPSS object managed jointly by the Core Server and the Physical Volume 
Library that represents the portion of a virtual volume. A virtual volume may be 
composed of one or more physical volumes, but a physical volume may contain 
data from no more than one virtual volume. 

An HPSS server that manages mounts and dismounts of HPSS physical volumes. 

An HPSS server that manages the robotic agent responsible for mounting and 
dismounting cartridges or interfaces with the human agent responsible for 
mounting and dismounting cartridges. 

Parallel I/O 

Parallel I/O File System 

Portable Operating System Interface (for computer environments) 

Deletion of file data from a level in the file’s hierarchy after the data has been 
duplicated at lower levels in the hierarchy and is no longer needed at the deletion 
level. 

A lock applied to a bitfile which prohibits the bitfile from being purged. 

Physical Volume 
Physical Volume Library 
Physical Volume Manager 
Physical Volume Repository 
Redundant Array of Independent Disks 
Redundant Array of Independent Tapes 
Random Access Memory 

The act of making empty tape virtual volumes available for reuse. Reclaimed 
tape virtual volumes are assigned a new Virtual Volume ID, but retain the rest of 
their previous characteristics. 

The process by which SSM requests notification of changes to specified 
attributes of a managed object. 

An HPSS SSM administrative operation that directs an HPSS server to reread its 
latest configuration information, and to change its operating parameters to match 
that configuration, without going through a server shutdown and restart. 
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repack 

request 

RISC 

RMS 

RPC 

SCSI 

security 

SGI 

shelf tape 

shutdown 

sink 

SMC 

SMIT 

SNL 

SOID 

source 

SP 

SS 

SSA 

SSM 


The act of moving data from a virtual volume onto another virtual volume with 
the same characteristics with the intention of removing all data from the source 
virtual volume. 

A log record message type used to log some action being performed by an HPSS 
server on behalf of a client. 

Reduced Instruction Set Computer/Cycles 

Removable Media Service 

Remote Procedure Call 

Small Computer Systems Interface 

A log record message type used to log security related events (e.g., authorization 
failures). 

Silicon Graphics 

A cartridge which has been physically removed from a tape library but whose file 
metadata still resides in HPSS. 

An HPSS SSM administrative operation that causes a server to stop its execution 
gracefully. 

The set of destinations to which data is sent during a data transfer (e.g., disk 
devices, memory buffers, network addresses). 

SCSI Medium Changer 

System Management Interface Tool 

Sandia National Laboratories 

Storage Object ID. An internal HPSS storage object identifier that uniquely 
identifies a storage resource. The SOID contains an unique identifier for the 
object, and an unique identifier for the server that manages the object. 

The set of origins from which data is received during a data transfer (e.g., disk 
devices, memory buffers, network addresses). 

Scalable Processor 

HPSS Storage Service 

Serial Storage Architecture 

Storage System Management 
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SSM session 

stage 

start-up 

status 

STK 

storage class 

storage hierarchy 

storage level 
storage map 

storage segment 
Storage Service 
storage subsystem 
Storage System Management 
stripe length 


The environment in which an SSM user interacts with the SSM System Manager 
to monitor and control HPSS. This environment may be the graphical user 
interface provided by the hpssgui program, or the command line user interface 
provided by the hpssadm program. 

To copy file data from a level in the file’s hierarchy onto the top level in the 
hierarchy. 

An HPSS SSM administrative operation that causes a server to begin execution. 

A log record message type used to log processing results. This message type is 
being used to report status from the HPSS Accounting process. 

Storage Technology Corporation 

An HPSS object used to group storage media together to provide storage for 
HPSS data with specific characteristics. The characteristics are both physical and 
logical. 

An ordered collection of storage classes. The hierarchy consists of a fixed 
number of storage levels numbered from level 1 to the number of levels in the 
hierarchy, with the maximum level being limited to 5 by HPSS. Each level is 
associated with a specific storage class. Migration and stage commands result in 
data being copied between different storage levels in the hierarchy. Each Class of 
Service has an associated hierarchy. 

The relative position of a single storage class in a storage hierarchy. For 
example, if a storage class is at the top of a hierarchy, the storage level is 1. 

An HPSS object managed by the Core Server to keep track of allocated storage 
space. 

An HPSS object managed by the Core Server to provide abstract storage for a 
bitfile or parts of a bitfile. 

The portion of the Core Server which provides control over a hierarchy of virtual 
and physical storage resources. 

A portion of the HPSS namespace that is managed by an independent Core 
Server and (optionally) Migration/Purge Server. 

An HPSS component that provides monitoring and control of HPSS via a 
windowed operator interface or command line interface. 

The number of bytes that must be written to span all the physical storage media 
(physical volumes) that are grouped together to form the logical storage media 
(virtual volume). The stripe length equals the virtual volume block size 
multiplied by the number of physical volumes in the stripe group (i.e., stripe 
width). 
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stripe length 

stripe width 
System Manager 

TB 

TCP/IP 

trace 

transaction 


TTY 

UDP 

UID 

UPC 

UUID 

virtual volume 

virtual volume block size 

VV 


The number of bytes that must be written to span all the physical storage media 
(physical volumes) that are grouped together to form the logical storage media 
(virtual volume). The stripe length equals the virtual volume block size 
multiplied by the number of physical volumes in the stripe group (i.e., stripe 
width). 

The number of physical volumes grouped together to represent a virtual volume. 

The Storage System Management (SSM) server. It communicates with all other 
HPSS components requiring monitoring or control. It also communicates with 
the SSM graphical user interface (hpssgui) and command line interface 
(hpssadm). 

Terabyte (2 40 ) 

Transmission Control Protocol/Intemet Protocol 

A log record message type used to record entry/exit processing paths through 
HPSS server software. 

A programming construct that enables multiple data operations to possess the 
following properties: 

All operations commit or abort/roll-back together such that they form a single 
unit of work. 

All data modified as part of the same transaction are guaranteed to maintain a 
consistent state whether the transaction is aborted or committed. 

Data modified from one transaction are isolated from other transactions until the 
transaction is either committed or aborted. 

Once the transaction commits, all changes to data are guaranteed to be 
permanent. 

Teletypewriter 

User Datagram Protocol 

User Identifier 

Universal Product Code 

Universal Unique Identifier 

An HPSS object managed by the Core Server that is used to represent logical 
media. A virtual volume is made up of a group of physical storage media (a 
stripe group of physical volumes). 

The size of the block of data bytes that is written to each physical volume of a 
striped virtual volume before switching to the next physical volume. 

Virtual Volume 
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XDSM 


The Open Group’s Data Storage Management standard. It defines APIs that use 
events to notify Data Management applications about operations on files. 


XFS 


A file system created by SGI available as open source for the Linux operating 
system. 
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